{"openapi":"3.1.0","info":{"title":"Nodavyr","description":"SEC filing intelligence API for developers and autonomous agents, provided by Nodavyr.","version":"0.1.0"},"servers":[{"url":"https://nodavyr.com","description":"Canonical Nodavyr service"}],"paths":{"/v1/signup":{"post":{"tags":["Access"],"summary":"Create a Nodavyr API credential","description":"Create a customer and issue an API key. The raw API key is returned only in this response.","operationId":"signup_v1_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"404":{"description":"Public signup is disabled"},"400":{"description":"Unable to provision customer"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"tags":["Health"],"summary":"Check service health","description":"Return the current Nodavyr service health status.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/intelligence/{ticker}":{"get":{"tags":["Intelligence"],"summary":"Get full filing intelligence","description":"Return the complete Nodavyr result derived from SEC company facts and filing comparison. Successful requests are metered.","operationId":"v1_intelligence_v1_intelligence__ticker__get","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Case-insensitive stock ticker, normalized to the canonical SEC ticker.","title":"Ticker"},"description":"Case-insensitive stock ticker, normalized to the canonical SEC ticker."},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"x402 v2 payment payload. Required only when FILINGEDGE_X402_ENABLED is true.","title":"Payment-Signature"},"description":"x402 v2 payment payload. Required only when FILINGEDGE_X402_ENABLED is true."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Company not found"},"503":{"description":"Authentication service unavailable"},"402":{"description":"x402 payment required, invalid, replayed, or not settled","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment requirements","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 v2 settlement response","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agent/{ticker}":{"get":{"tags":["Agent API"],"summary":"Get concise filing intelligence","description":"Return the highest-ranked existing Nodavyr insight in a compact, stable response. Two access modes are supported: an authenticated API-key request with x402, or keyless x402 with no Nodavyr signup or API key. In keyless mode, request this endpoint, receive HTTP 402 and inspect the PAYMENT-REQUIRED challenge, validate its x402 v2 exact Base Sepolia testnet; 100000 atomic test USDC ($0.10) requirements, supply the required payment-identifier, and retry with PAYMENT-SIGNATURE to receive JSON intelligence. The current profile is test-value only and is not a mainnet offering. The signal is not a trading recommendation. Successful requests are metered.","operationId":"v1_agent_v1_agent__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Case-insensitive stock ticker, normalized to the canonical SEC ticker.","title":"Ticker"},"description":"Case-insensitive stock ticker, normalized to the canonical SEC ticker."},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"x402 v2 payment payload. Required only when FILINGEDGE_X402_ENABLED is true.","title":"Payment-Signature"},"description":"x402 v2 payment payload. Required only when FILINGEDGE_X402_ENABLED is true."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"401":{"description":"Invalid or missing API key"},"404":{"description":"Company not found"},"503":{"description":"Authentication service unavailable"},"402":{"description":"x402 payment required, invalid, replayed, or not settled","headers":{"PAYMENT-REQUIRED":{"description":"Base64-encoded x402 v2 payment requirements","schema":{"type":"string"}},"PAYMENT-RESPONSE":{"description":"Base64-encoded x402 v2 settlement response","schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{},{"APIKeyHeader":[]}]}},"/v1/recovery/challenge":{"post":{"tags":["Agent API"],"summary":"Create a paid-result recovery challenge","description":"Create a five-minute, single-use EIP-191 wallet challenge for an available paid agent result. This endpoint never initiates payment.","operationId":"recovery_challenge_v1_recovery_challenge_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryChallengeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryChallengeResponse"}}}},"404":{"description":"Recovery result unavailable"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/recovery":{"post":{"tags":["Agent API"],"summary":"Recover a previously purchased agent result","description":"Return the original stored AgentResponse after an EIP-191 wallet signature proves control of the EOA wallet that paid. Recovery is free and never executes intelligence, settles payment, creates usage, or increments request_number.","operationId":"recover_paid_result_v1_recovery_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentResponse"}}}},"401":{"description":"Invalid recovery authorization"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"tags":["Usage"],"summary":"Get authenticated customer usage","description":"Return successful usage aggregated for the authenticated customer and separately for the key used for this request. This endpoint is not metered.","operationId":"v1_usage_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Invalid or missing API key"},"503":{"description":"Authentication service unavailable"}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"AgentResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Normalized public-company ticker symbol for the analyzed issuer."},"signal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal","description":"Highest-ranked Nodavyr intelligence signal selected for the company."},"direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Direction","description":"Direction of the signal, such as positive, negative, or neutral when available."},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence","description":"Nodavyr confidence in the selected signal, expressed as a value from 0.0 to 1.0."},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score","description":"Relative importance score assigned to the selected signal; higher values indicate greater significance."},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Concise natural-language explanation of the selected filing or financial signal."},"materiality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Materiality","description":"Qualitative materiality classification for the signal, such as low, medium, or high."},"request_number":{"type":"integer","title":"Request Number","description":"Successful metered-request sequence for the authenticated API key or keyless payer wallet."}},"type":"object","required":["ticker","signal","direction","confidence","score","summary","materiality","request_number"],"title":"AgentResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","const":"ok","title":"Status"},"service":{"type":"string","const":"FilingEdge","title":"Service"}},"type":"object","required":["status","service"],"title":"HealthResponse"},"RecoveryChallengeRequest":{"properties":{"payment_identifier":{"type":"string","maxLength":256,"minLength":16,"title":"Payment Identifier"},"payer_wallet":{"type":"string","maxLength":42,"minLength":42,"title":"Payer Wallet"}},"type":"object","required":["payment_identifier","payer_wallet"],"title":"RecoveryChallengeRequest"},"RecoveryChallengeResponse":{"properties":{"nonce":{"type":"string","title":"Nonce"},"message":{"type":"string","title":"Message"},"expires_at":{"type":"string","title":"Expires At"}},"type":"object","required":["nonce","message","expires_at"],"title":"RecoveryChallengeResponse"},"RecoveryRequest":{"properties":{"payment_identifier":{"type":"string","maxLength":256,"minLength":16,"title":"Payment Identifier"},"payer_wallet":{"type":"string","maxLength":42,"minLength":42,"title":"Payer Wallet"},"nonce":{"type":"string","maxLength":128,"minLength":32,"title":"Nonce"},"signature":{"type":"string","maxLength":132,"minLength":130,"title":"Signature"}},"type":"object","required":["payment_identifier","payer_wallet","nonce","signature"],"title":"RecoveryRequest"},"SignupRequest":{"properties":{"name":{"type":"string","maxLength":120,"minLength":2,"title":"Name"},"key_name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Key Name","default":"default"},"company_website":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Company Website"}},"type":"object","required":["name"],"title":"SignupRequest"},"SignupResponse":{"properties":{"customer_id":{"type":"string","title":"Customer Id"},"api_key_id":{"type":"string","title":"Api Key Id"},"api_key":{"type":"string","title":"Api Key"},"key_prefix":{"type":"string","title":"Key Prefix"},"warning":{"type":"string","title":"Warning","default":"Store this API key securely. FilingEdge will not display it again."}},"type":"object","required":["customer_id","api_key_id","api_key","key_prefix"],"title":"SignupResponse"},"UsageResponse":{"properties":{"request_count":{"type":"integer","title":"Request Count"},"api_key_request_count":{"type":"integer","title":"Api Key Request Count"},"metering":{"type":"string","const":"sqlite","title":"Metering"},"as_of":{"type":"string","title":"As Of"}},"type":"object","required":["request_count","api_key_request_count","metering","as_of"],"title":"UsageResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Health","description":"Service availability checks."},{"name":"Access","description":"Customer signup and API credential provisioning."},{"name":"Agent API","description":"Compact x402 intelligence with optional API-key attribution."},{"name":"Intelligence","description":"Full authenticated SEC filing intelligence."},{"name":"Usage","description":"Authenticated customer and API-key usage totals."}]}