{"openapi":"3.1.0","info":{"title":"Trust Engine API","version":"1.1.0","description":"Evaluates risk and trustworthiness of phone numbers, crypto tokens, and properties. Returns a trust score (0–100), decision (safe/warning/high_risk), risk flags, and a human-readable summary. Designed for LLM tool calling, agent frameworks, and direct integration.","contact":{"name":"Spark Engineering","url":"https://sparkengineering.co"}},"servers":[{"url":"https://trustscore.dev","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/api/score":{"post":{"operationId":"get_trust_score","summary":"Evaluate trust score for a single input","description":"Accepts a type and input, routes to the domain module, and returns a trust assessment. Use type=\"phone\" with phone_number, type=\"token\" with address, or type=\"property\" with address.","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustScoreRequest"},"examples":{"phone":{"summary":"Check a US phone number","value":{"type":"phone","input":{"phone_number":"+15551234567"}}},"token":{"summary":"Check a crypto token (coming soon)","value":{"type":"token","input":{"address":"0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"}}},"property":{"summary":"Check a property (coming soon)","value":{"type":"property","input":{"address":"123 Main St, Springfield, IL"}}}}}}},"responses":{"200":{"description":"Trust score result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrustScoreResponse"},"example":{"score":97,"confidence":0.75,"decision":"safe","signals":{"e164":"+15551234567","valid":true,"carrier":"T-Mobile","line_type":"Wireless","is_voip":false,"fraud_score":0,"active":true,"spammer":false},"risk_flags":[],"summary":"This number appears trustworthy with a score of 97/100.","_meta":{"latency_ms":342,"type":"phone","sources":["libphonenumber","ipqs"]}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown module type","content":{"application/json":{"schema":{"type":"object","required":["error","code","valid_types"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["UNKNOWN_TYPE"]},"valid_types":{"type":"array","items":{"type":"string"}}}}}}},"429":{"description":"Rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/batch-score":{"post":{"operationId":"batch_trust_score","summary":"Evaluate trust scores for multiple inputs","description":"Accepts an array of up to 25 items and returns results for each. Items are processed in parallel. Each item follows the same schema as POST /api/score. Failed items return an error string instead of a result.","security":[{"ApiKeyAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScoreRequest"},"example":{"items":[{"type":"phone","input":{"phone_number":"+15551234567"}},{"type":"phone","input":{"phone_number":"+18005550199"}}]}}}},"responses":{"200":{"description":"Batch results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScoreResponse"}}}},"400":{"description":"Invalid request or batch too large (max 25)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/health":{"get":{"operationId":"health_check","summary":"Health check","description":"Returns server status, registered modules, and timestamp.","security":[],"responses":{"200":{"description":"Server is healthy","content":{"application/json":{"schema":{"type":"object","required":["status","modules","timestamp"],"properties":{"status":{"type":"string","enum":["ok"]},"modules":{"type":"array","items":{"type":"string"},"description":"Registered module types"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"/api/openapi":{"get":{"operationId":"get_openapi_spec","summary":"OpenAPI specification","description":"Returns this OpenAPI 3.1 specification as JSON.","security":[],"responses":{"200":{"description":"OpenAPI spec JSON"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key for authenticated access. Format: Bearer <key>. Not required for MVP."}},"schemas":{"TrustScoreRequest":{"type":"object","required":["type","input"],"discriminator":{"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/PhoneScoreRequest"},{"$ref":"#/components/schemas/TokenScoreRequest"},{"$ref":"#/components/schemas/PropertyScoreRequest"}]},"PhoneScoreRequest":{"type":"object","required":["type","input"],"properties":{"type":{"type":"string","const":"phone"},"input":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"Phone number in E.164, national, or formatted form. E.g. \"+15551234567\" or \"(555) 123-4567\".","examples":["+15551234567","(704) 460-7025","+44 20 7946 0958"]}}}}},"TokenScoreRequest":{"type":"object","required":["type","input"],"properties":{"type":{"type":"string","const":"token"},"input":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"Token contract address (EVM hex or Solana base58).","examples":["0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984"]},"chain":{"type":"string","description":"Blockchain identifier. Defaults to \"ethereum\".","examples":["ethereum","polygon","solana"]}}}}},"PropertyScoreRequest":{"type":"object","required":["type","input"],"properties":{"type":{"type":"string","const":"property"},"input":{"type":"object","required":["address"],"properties":{"address":{"type":"string","description":"Full property address.","examples":["123 Main St, Springfield, IL 62701"]}}}}},"TrustScoreResponse":{"type":"object","required":["score","confidence","decision","signals","risk_flags","summary","_meta"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100,"description":"Trust score. 100 = most trustworthy, 0 = highest risk."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence in the score. Higher when more data sources contributed (e.g. 0.75 = libphonenumber + IPQS)."},"decision":{"type":"string","enum":["safe","warning","high_risk"],"description":"Actionable decision derived from the score. safe (>=70), warning (40-69), high_risk (<40)."},"signals":{"type":"object","additionalProperties":true,"description":"Raw signals from all data sources. Shape varies by module type."},"risk_flags":{"type":"array","items":{"type":"string"},"description":"Human-readable risk indicators. E.g. \"VoIP number\", \"Known spammer\", \"High fraud score\", \"Number found in data breach\"."},"summary":{"type":"string","description":"Human-readable summary of the trust evaluation."},"_meta":{"type":"object","required":["latency_ms","type","sources"],"properties":{"latency_ms":{"type":"integer","description":"Server-side processing time in milliseconds."},"type":{"type":"string","description":"Module type used for evaluation."},"sources":{"type":"array","items":{"type":"string"},"description":"Data sources that contributed signals. E.g. [\"libphonenumber\", \"ipqs\", \"skipcalls\"]."}}}}},"BatchScoreRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/TrustScoreRequest"},"description":"Array of trust score requests. Max 25 items."}}},"BatchScoreResponse":{"type":"object","required":["results","count"],"properties":{"results":{"type":"array","items":{"type":"object","required":["index"],"properties":{"index":{"type":"integer","description":"Position in the input array (0-based)."},"result":{"$ref":"#/components/schemas/TrustScoreResponse"},"error":{"type":"string","description":"Error message if this item failed."}}}},"count":{"type":"integer","description":"Number of items processed."}}},"ErrorResponse":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","description":"Human-readable error message."},"code":{"type":"string","enum":["INVALID_JSON","MISSING_FIELDS","UNKNOWN_TYPE","BATCH_TOO_LARGE","INTERNAL_ERROR"],"description":"Machine-readable error code."},"detail":{"type":"string","description":"Additional detail about the error."},"example":{"type":"object","description":"Example of a valid request."},"valid_types":{"type":"array","items":{"type":"string"},"description":"List of valid module types (for UNKNOWN_TYPE errors)."}}}}}}