{"openapi":"3.1.0","info":{"title":"Lumind Agent API","version":"1.0.0","description":"Programmatic surface for AI agents to run GEO/SEO citation scans, paid from the LUM balance of the human owner that mandates the agent, bounded by caps."},"servers":[{"url":"/"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"Agent key issued by the owner: `Authorization: Bearer lmd_agent_...`"}},"schemas":{"WalletSnapshot":{"type":"object","properties":{"walletBalance":{"type":"integer"},"totalCap":{"type":"integer"},"spent":{"type":"integer"},"remaining":{"type":"integer"},"dailyCap":{"type":["integer","null"]},"dailyRemaining":{"type":["integer","null"]}}},"Service":{"type":"object","properties":{"serviceId":{"type":"string"},"name":{"type":"string"},"lumCost":{"type":"integer"}}},"ScanRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"},"options":{"type":"object"}}},"ScanCreated":{"type":"object","properties":{"scanId":{"type":"string"},"reportToken":{"type":"string"},"balance":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"security":[{"agentKey":[]}],"paths":{"/v1/agent/wallet":{"get":{"summary":"Budget snapshot (balance + caps + remaining)","operationId":"getAgentWallet","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletSnapshot"}}}}}}},"/v1/agent/services":{"get":{"summary":"Machine catalogue of services and their LUM cost","operationId":"listAgentServices","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}}}}},"/v1/agent/scans":{"post":{"summary":"Run a GEO/SEO scan (money-first: capped LUM debited then enqueued)","operationId":"createAgentScan","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client key making a retry exactly-once."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"201":{"description":"Scan enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanCreated"}}}},"402":{"description":"Not enough LUM","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Cap exceeded / service not allowed / key unusable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Daily cap exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Scan engine error (LUM refunded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Scan not available yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/agent/scans/{id}":{"get":{"summary":"Scan status","operationId":"getAgentScan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}},"/v1/agent/scans/{id}/report":{"get":{"summary":"Scan report (JSON default, or Markdown)","operationId":"getAgentScanReport","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}}}},"x-lumind":{"scanLumCost":1900}}