{"openapi":"3.0.3","info":{"title":"AI API","description":"API for AI-powered customer analysis, wallet and transaction screening analysis","version":"0.0.1"},"servers":[{"url":"https://ai-api.elliptic.co","description":"Production server"}],"tags":[{"name":"Health","description":"Health check endpoints"},{"name":"Screenings","description":"Wallet and transaction screening endpoints"},{"name":"Customers","description":"Customer analysis endpoints"}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Health check","description":"Returns OK if the service is running","operationId":"healthCheck","security":[],"responses":{"200":{"description":"Service is healthy","content":{"text/plain":{"schema":{"type":"string","example":"OK"}}}}}}},"/copilot/wallet/{screeningId}":{"get":{"tags":["Screenings"],"summary":"Get wallet summary","description":"Returns an AI-generated summary for a wallet screening","operationId":"getWalletSummary","parameters":[{"name":"screeningId","in":"path","required":true,"description":"Wallet screening ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}],"responses":{"200":{"description":"AI-generated wallet summary","content":{"text/plain":{"schema":{"type":"string","description":"LLM-generated narrative about the wallet screening"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/copilot/wallet/riskgraph/{direction}/{screeningId}":{"post":{"tags":["Screenings"],"summary":"Get wallet risk graph summary for a single entity","description":"Returns an AI-generated summary of the risk graph for a wallet in the specified direction, scoped to a single entity provided in the request body","operationId":"postWalletRiskGraph","parameters":[{"name":"direction","in":"path","required":true,"description":"Graph direction","schema":{"type":"string","enum":["forwards","backwards"],"example":"forwards"}},{"name":"screeningId","in":"path","required":true,"description":"Wallet screening ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskGraphEntity"}}}},"responses":{"200":{"description":"AI-generated wallet risk graph summary for the given entity","content":{"text/plain":{"schema":{"type":"string","description":"LLM-generated narrative about the entity in the wallet risk graph"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/copilot/wallet/entities/{direction}/{screeningId}":{"get":{"tags":["Screenings"],"summary":"Get wallet risk graph entities","description":"Returns the entities associated with a wallet risk graph","operationId":"getWalletEntities","parameters":[{"name":"direction","in":"path","required":true,"description":"Graph direction","schema":{"type":"string","enum":["forwards","backwards"],"example":"forwards"}},{"name":"screeningId","in":"path","required":true,"description":"Wallet screening ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}],"responses":{"200":{"description":"Wallet risk graph entities","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskGraphEntities"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/copilot/transaction/{screeningId}":{"get":{"tags":["Screenings"],"summary":"Get transaction summary","description":"Returns an AI-generated summary for a transaction screening","operationId":"getTransactionSummary","parameters":[{"name":"screeningId","in":"path","required":true,"description":"Transaction screening ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}],"responses":{"200":{"description":"AI-generated transaction summary","content":{"text/plain":{"schema":{"type":"string","description":"LLM-generated narrative about the transaction screening"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/copilot/transaction/riskgraph/{screeningId}":{"post":{"tags":["Screenings"],"summary":"Get transaction risk graph summary for a single entity","description":"Returns an AI-generated summary of the risk graph for a transaction, scoped to a single entity provided in the request body","operationId":"postTransactionRiskGraph","parameters":[{"name":"screeningId","in":"path","required":true,"description":"Transaction screening ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RiskGraphEntity"}}}},"responses":{"200":{"description":"AI-generated transaction risk graph summary for the given entity","content":{"text/plain":{"schema":{"type":"string","description":"LLM-generated narrative about the entity in the transaction risk graph"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/copilot/transaction/entities/{screeningId}":{"get":{"tags":["Screenings"],"summary":"Get transaction risk graph entities","description":"Returns the entities associated with a transaction risk graph","operationId":"getTransactionEntities","parameters":[{"name":"screeningId","in":"path","required":true,"description":"Transaction screening ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}],"responses":{"200":{"description":"Transaction risk graph entities","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RiskGraphEntities"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/copilot/customers/summary/{customerId}":{"get":{"tags":["Customers"],"summary":"Get customer summary","description":"Returns a summary for a customer by ID. The shape of the response depends on the `request` query parameter.","operationId":"getCustomerSummary","parameters":[{"name":"customerId","in":"path","required":true,"description":"Customer ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}},{"name":"request","in":"query","required":false,"description":"Type of summary to return. Omit for a full structured summary with analysis IDs. `overview`, `wallet`, or `transaction` return an LLM narrative. `wallet_ids` or `transaction_ids` return the highest-risk items with their hash and analysis ID.","schema":{"type":"string","enum":["overview","wallet","transaction","wallet_ids","transaction_ids"],"example":"overview"}}],"responses":{"200":{"description":"Customer summary. Shape depends on `request` query param: `SummaryResult` when omitted, LLM narrative string for `overview`/`wallet`/`transaction`, or `MaxRiskTrigger[]` for `wallet_ids`/`transaction_ids`.","content":{"text/plain":{"schema":{"type":"string","description":"LLM-generated narrative (returned when request is overview, wallet, or transaction)"}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SummaryResult"},{"type":"array","items":{"$ref":"#/components/schemas/MaxRiskTrigger"},"description":"Highest-risk items with hash and analysisId (returned when request is wallet_ids or transaction_ids)"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/copilot/customers/summary/{customerId}/transaction-assets":{"get":{"tags":["Customers"],"summary":"Get customer transaction assets","description":"Returns an AI-generated analysis of transaction assets for a customer","operationId":"getTransactionAssetsByCustomerId","parameters":[{"name":"customerId","in":"path","required":true,"description":"Customer ID (UUID)","schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"}}],"responses":{"200":{"description":"AI-generated transaction assets analysis","content":{"text/plain":{"schema":{"type":"string","description":"LLM-generated narrative about the customer's transaction assets"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"securitySchemes":{"Bearer":{"description":"Bearer Authentication","type":"http","scheme":"bearer","bearerFormat":"JWT"},"apiKey":{"description":"API Key","type":"apiKey","in":"header","name":"x-access-key"},"signature":{"description":"(Request Time, HTTP Method, Lowercase Path, Request Payload) signed with API Secret","type":"apiKey","in":"header","name":"x-access-sign"},"timestamp":{"type":"apiKey","in":"header","name":"x-access-timestamp"}},"schemas":{"AiResponseItem":{"type":"object","properties":{"title":{"type":"string","description":"Title of the response item"},"body":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"narrative":{"type":"string"}}}},{"type":"array","items":{"$ref":"#/components/schemas/AiResponseItem"}}]}},"required":["title","body"]},"RiskGraphEntity":{"type":"object","description":"A single entity in a risk graph, used when requesting graph analysis scoped to a specific entity","properties":{"name":{"type":"string","description":"Entity name"},"perc":{"type":"number","description":"Direct exposure percentage"},"usd":{"type":"number","description":"Direct exposure in USD"},"indirect_perc":{"type":"number","description":"Indirect exposure percentage"},"indirect_usd":{"type":"number","description":"Indirect exposure in USD"},"min_hops":{"type":"number","description":"Minimum number of hops to the entity in the graph"},"category":{"type":"string","description":"Entity category"}},"required":["perc","usd"]},"RiskGraphEntities":{"type":"object","properties":{"score":{"type":"number","description":"Overall risk score"},"entities":{"type":"array","items":{"$ref":"#/components/schemas/RiskGraphEntity"}}},"required":["score","entities"]},"MaxRiskTrigger":{"type":"object","description":"A wallet or transaction at the maximum risk score, with its hash and analysis ID","properties":{"hash":{"type":"string","description":"Wallet address or transaction hash"},"analysisId":{"type":"string","format":"uuid","description":"Analysis ID (UUID)"}},"required":["hash","analysisId"]},"SummaryResult":{"type":"object","description":"Full customer summary including an LLM narrative and the analysis IDs used to generate it","properties":{"summary":{"type":"string","description":"LLM-generated customer summary"},"analysisIds":{"type":"object","properties":{"wallets":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Wallet analysis IDs used in the summary"},"transactions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Transaction analysis IDs used in the summary"}},"required":["wallets","transactions"]}},"required":["summary","analysisIds"]},"AnalysesEntityInfoDto":{"type":"object","properties":{"analysisIds":{"type":"object","properties":{"transactions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Transaction analysis IDs"},"wallets":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Wallet analysis IDs"}},"required":["transactions","wallets"]}},"required":["analysisIds"]},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error message"},"statusCode":{"type":"integer","description":"HTTP status code"},"timestamp":{"type":"string","format":"date-time","description":"Timestamp of the error"},"context":{"type":"object","additionalProperties":true,"description":"Additional error context"}},"required":["message","statusCode","timestamp"]}},"responses":{"BadRequest":{"description":"Bad request - Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Validation failed","statusCode":400,"timestamp":"2024-01-01T00:00:00.000Z","context":{"errors":["Customer ID must be a valid UUID"]}}}}},"Unauthorized":{"description":"Unauthorized - Missing or invalid authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Unauthorized","statusCode":401,"timestamp":"2024-01-01T00:00:00.000Z"}}}},"Forbidden":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Forbidden - Insufficient permissions","statusCode":403,"timestamp":"2024-01-01T00:00:00.000Z"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Resource not found","statusCode":404,"timestamp":"2024-01-01T00:00:00.000Z"}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"message":"Internal server error","statusCode":500,"timestamp":"2024-01-01T00:00:00.000Z"}}}}}},"x-readme":{"explorer-enabled":true},"security":[{"Bearer":[]},{"apiKey":[],"signature":[],"timestamp":[]}]}