{"openapi":"3.1.0","info":{"title":"VectorFin API","description":"AI-native financial embeddings and quant signals for institutional data engineers.","version":"0.1.0"},"paths":{"/health":{"get":{"tags":["meta"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","title":"Response Health Health Get"}}}}}}},"/orgs":{"post":{"tags":["orgs"],"summary":"Create Org","description":"Create a new organisation and issue its first API key.\nThe full API key is returned exactly once — store it securely.","operationId":"create_org_orgs_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgWithKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orgs/{org_id}/api-keys":{"post":{"tags":["orgs"],"summary":"Issue Api Key","description":"Issue a new API key for an org.\nRequires a valid, non-revoked API key that belongs to this org.","operationId":"issue_api_key_orgs__org_id__api_keys_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["orgs"],"summary":"List Api Keys","description":"List all non-revoked API keys for the org.","operationId":"list_api_keys_orgs__org_id__api_keys_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyListItem"},"title":"Response List Api Keys Orgs  Org Id  Api Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orgs/me":{"get":{"tags":["orgs"],"summary":"Get My Org","description":"Return the org for the authenticated API key.","operationId":"get_my_org_orgs_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/orgs/{org_id}":{"get":{"tags":["orgs"],"summary":"Get Org","description":"Return org details.","operationId":"get_org_orgs__org_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orgs/{org_id}/api-keys/{key_id}":{"delete":{"tags":["orgs"],"summary":"Revoke Api Key","description":"Revoke an API key.\nRequires a valid API key belonging to this org.\nAn org can revoke any of its own keys (including the key used to make this call).","operationId":"revoke_api_key_orgs__org_id__api_keys__key_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orgs/{org_id}/usage/{period}":{"get":{"tags":["orgs"],"summary":"Get Org Usage","description":"Return usage for the org. Defaults to current month; pass YYYY-MM for a specific month.","operationId":"get_org_usage_orgs__org_id__usage__period__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"period","in":"path","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orgs/{org_id}/usage":{"get":{"tags":["orgs"],"summary":"Get Org Usage","description":"Return usage for the org. Defaults to current month; pass YYYY-MM for a specific month.","operationId":"get_org_usage_orgs__org_id__usage_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","title":"Org Id"}},{"name":"period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orgs/{org_id}/stripe/checkout":{"post":{"tags":["billing"],"summary":"Stripe Checkout","description":"Create a Stripe Checkout session for the authenticated org.","operationId":"stripe_checkout_orgs__org_id__stripe_checkout_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stripe/checkout":{"post":{"tags":["billing"],"summary":"Stripe Checkout","description":"Create a Stripe Checkout session for the authenticated org.","operationId":"stripe_checkout_stripe_checkout_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/orgs/{org_id}/stripe/portal":{"post":{"tags":["billing"],"summary":"Stripe Portal","description":"Create a Stripe Billing Portal session for the authenticated org.","operationId":"stripe_portal_orgs__org_id__stripe_portal_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stripe/portal":{"post":{"tags":["billing"],"summary":"Stripe Portal","description":"Create a Stripe Billing Portal session for the authenticated org.","operationId":"stripe_portal_stripe_portal_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"org_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/stripe/webhook":{"post":{"tags":["billing"],"summary":"Stripe Webhook","description":"Stripe webhook endpoint.\nNo API key auth — Stripe signature is verified internally.\nMUST read raw bytes before any JSON parsing.","operationId":"stripe_webhook_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/embeddings/{ticker}":{"get":{"tags":["data"],"summary":"Get Embeddings","operationId":"get_embeddings_v1_embeddings__ticker__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"fiscal_period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"e.g. 2024-Q3","title":"Fiscal Period"},"description":"e.g. 2024-Q3"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EmbeddingRecord"},"title":"Response Get Embeddings V1 Embeddings  Ticker  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signals/{ticker}":{"get":{"tags":["data"],"summary":"Get Signals","operationId":"get_signals_v1_signals__ticker__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO date YYYY-MM-DD","title":"Date From"},"description":"ISO date YYYY-MM-DD"},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"ISO date YYYY-MM-DD","title":"Date To"},"description":"ISO date YYYY-MM-DD"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"default":30,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SignalRecord"},"title":"Response Get Signals V1 Signals  Ticker  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/tickers":{"get":{"tags":["data"],"summary":"Get Tickers","operationId":"get_tickers_v1_tickers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TickerListResponse"}}}}}}}},"components":{"schemas":{"ApiKeyCreateResponse":{"properties":{"key_id":{"type":"string","title":"Key Id"},"prefix":{"type":"string","title":"Prefix"},"key":{"type":"string","title":"Key"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["key_id","key_id","prefix","key","created_at"],"title":"ApiKeyCreateResponse","description":"Returned once on key creation — the raw key is NEVER stored or returned again."},"ApiKeyListItem":{"properties":{"key_id":{"type":"string","title":"Key Id"},"prefix":{"type":"string","title":"Prefix"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"revoked":{"type":"boolean","title":"Revoked"}},"type":"object","required":["key_id","key_id","prefix","created_at","last_used_at","revoked"],"title":"ApiKeyListItem"},"CheckoutRequest":{"properties":{"plan":{"type":"string","enum":["starter","pro"],"title":"Plan"},"success_url":{"type":"string","title":"Success Url"},"cancel_url":{"type":"string","title":"Cancel Url"}},"type":"object","required":["plan","success_url","cancel_url"],"title":"CheckoutRequest"},"CheckoutResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url"}},"type":"object","required":["checkout_url"],"title":"CheckoutResponse"},"EmbeddingRecord":{"properties":{"ticker":{"type":"string","title":"Ticker"},"fiscal_period":{"type":"string","title":"Fiscal Period"},"chunk_idx":{"type":"integer","title":"Chunk Idx"},"effective_ts":{"type":"string","format":"date-time","title":"Effective Ts"},"knowledge_ts":{"type":"string","format":"date-time","title":"Knowledge Ts"},"model_version":{"type":"string","title":"Model Version"},"embedding":{"items":{"type":"number"},"type":"array","title":"Embedding"}},"type":"object","required":["ticker","fiscal_period","chunk_idx","effective_ts","knowledge_ts","model_version","embedding"],"title":"EmbeddingRecord"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OrgCreate":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["name","email"],"title":"OrgCreate"},"OrgResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"email":{"type":"string","title":"Email"},"plan":{"type":"string","enum":["free","starter","pro","enterprise"],"title":"Plan"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","name","email","plan","created_at"],"title":"OrgResponse"},"OrgWithKeyResponse":{"properties":{"org":{"$ref":"#/components/schemas/OrgResponse"},"api_key":{"$ref":"#/components/schemas/ApiKeyCreateResponse"}},"type":"object","required":["org","api_key"],"title":"OrgWithKeyResponse","description":"Returned on org creation — combines org info with the first API key."},"PortalRequest":{"properties":{"return_url":{"type":"string","title":"Return Url"}},"type":"object","required":["return_url"],"title":"PortalRequest"},"PortalResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url"}},"type":"object","required":["portal_url"],"title":"PortalResponse"},"SignalRecord":{"properties":{"ticker":{"type":"string","title":"Ticker"},"date":{"type":"string","title":"Date"},"score":{"type":"number","title":"Score"},"components":{"type":"object","title":"Components"},"effective_ts":{"type":"string","format":"date-time","title":"Effective Ts"},"knowledge_ts":{"type":"string","format":"date-time","title":"Knowledge Ts"}},"type":"object","required":["ticker","date","score","components","effective_ts","knowledge_ts"],"title":"SignalRecord"},"TickerListResponse":{"properties":{"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["tickers","total"],"title":"TickerListResponse"},"UsageResponse":{"properties":{"period":{"type":"string","title":"Period"},"plan":{"type":"string","enum":["free","starter","pro","enterprise"],"title":"Plan"},"api_calls":{"type":"integer","title":"Api Calls"},"embedding_lookups":{"type":"integer","title":"Embedding Lookups"},"signal_lookups":{"type":"integer","title":"Signal Lookups"},"batch_calls":{"type":"integer","title":"Batch Calls"},"limit_api_calls":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit Api Calls"}},"type":"object","required":["period","plan","api_calls","embedding_lookups","signal_lookups","batch_calls","limit_api_calls"],"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}