{"openapi":"3.0.3","info":{"title":"Causalytics Public API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Opaque API key shown once when created in settings."}},"schemas":{"Contact":{"type":"object","description":"Base contact record. Retrieve /contacts/{id} for enriched details.","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"type":{"type":"string"},"company_id":{"type":"string","format":"uuid","nullable":true},"company_name":{"type":"string","nullable":true,"description":"Associated company name, falling back to contact company data."},"connected_at":{"type":"string","format":"date-time","nullable":true,"description":"Earliest LinkedIn connection with the default site profile."},"state":{"type":"string"},"data":{"type":"object","additionalProperties":true},"meta":{"type":"object","additionalProperties":true}},"additionalProperties":true},"EnrichedContact":{"type":"object","description":"Full enriched contact view, including computed priority and LinkedIn details.","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"display_name":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"connected_at":{"type":"string","format":"date-time","nullable":true},"priority_rank":{"type":"integer","nullable":true},"priority_score":{"type":"number","nullable":true}},"additionalProperties":true},"Company":{"type":"object","description":"Enriched company record for the authenticated team.","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"marketing_name":{"type":"string","nullable":true},"business_id":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"company_region":{"type":"string","nullable":true},"company_size":{"type":"string","nullable":true},"company_industry":{"type":"string","nullable":true},"company_type":{"type":"string","nullable":true},"company_summary":{"type":"string","nullable":true},"contact_count":{"type":"integer"},"data":{"type":"object","additionalProperties":true},"meta":{"type":"object","additionalProperties":true}},"additionalProperties":true},"Interaction":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"owner_id":{"type":"string","format":"uuid"},"post_id":{"type":"string","format":"uuid","nullable":true},"type":{"type":"string"},"content":{"type":"string","nullable":true},"acted_from_name":{"type":"string","nullable":true,"description":"Actor profile name, slug, URN, or raw identifier."},"post_url":{"type":"string","nullable":true,"description":"URL of the matched post owned by the default site profile, if available."},"date":{"type":"string","format":"date-time","nullable":true}},"additionalProperties":true},"Post":{"type":"object","required":["id","analytics"],"properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":"string","format":"uuid"},"text":{"type":"string","nullable":true},"post_date":{"type":"string","format":"date-time","nullable":true},"theme":{"type":"string","description":"Post classifier category, or Unknown."},"personal":{"type":"integer","nullable":true,"description":"Personal classifier score."},"promotional":{"type":"integer","nullable":true,"description":"Promotional classifier score."},"analytics":{"nullable":true,"type":"object","description":"Latest analytics snapshot for this post and site, or null if none exists.","properties":{"date":{"type":"string","format":"date-time"},"impressions":{"type":"integer","nullable":true},"reactions":{"type":"integer","nullable":true},"comments":{"type":"integer","nullable":true},"saves":{"type":"integer","nullable":true},"followers_gained":{"type":"integer","nullable":true},"profile_views":{"type":"integer","nullable":true}}}},"additionalProperties":true},"Dm":{"type":"object","required":["id","participants"],"properties":{"id":{"type":"string","format":"uuid"},"content":{"type":"string","nullable":true},"date":{"type":"string","format":"date-time","nullable":true},"participants":{"type":"array","description":"Matching message-profile pairs involving the default site’s LinkedIn profile.","items":{"type":"object","properties":{"sent_from":{"type":"string","format":"uuid","nullable":true},"sent_to":{"type":"string","format":"uuid","nullable":true},"sent_from_name":{"type":"string","nullable":true,"description":"Sender name, slug, URN, or raw identifier."},"sent_to_name":{"type":"string","nullable":true,"description":"Recipient name, slug, URN, or raw identifier."}}}}},"additionalProperties":true},"Activity":{"type":"object","required":["site_id","date"],"properties":{"site_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date"},"posts_published":{"type":"integer","nullable":true},"comments":{"type":"integer","nullable":true},"user_reply_rate":{"type":"integer","nullable":true},"connection_requests":{"type":"integer","nullable":true},"request_acceptance_rate":{"type":"integer","nullable":true},"dm_sent":{"type":"integer","nullable":true}},"additionalProperties":false}}},"paths":{"/contacts":{"get":{"summary":"List contacts","description":"Base contacts with company name and first LinkedIn connection date for the default site profile.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"description":"Paginated results","content":{"application/json":{"schema":{"type":"object","required":["total","limit","skip","data"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}}}},"400":{"description":"Invalid pagination or unsupported query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"401":{"description":"API key missing, invalid, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"403":{"description":"Team subscription is not eligible for the public API","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"404":{"description":"Contact, site or LinkedIn profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"429":{"description":"100 requests per minute per team exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}},"headers":{"Retry-After":{"description":"Seconds until the next minute","schema":{"type":"integer"}}}},"503":{"description":"Public API rate limiter is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}}}}},"/contacts/{id}":{"get":{"summary":"Get an enriched contact","description":"Returns the full enriched contact, company name and first LinkedIn connection date.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Enriched contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichedContact"}}}},"400":{"description":"Invalid pagination or unsupported query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"401":{"description":"API key missing, invalid, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"403":{"description":"Team subscription is not eligible for the public API","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"404":{"description":"Contact, site or LinkedIn profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"429":{"description":"100 requests per minute per team exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}},"headers":{"Retry-After":{"description":"Seconds until the next minute","schema":{"type":"integer"}}}},"503":{"description":"Public API rate limiter is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}}}}},"/company/{id}":{"get":{"summary":"Get a company","description":"Returns an enriched company only when its base record belongs to the authenticated team.","security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Enriched company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"400":{"description":"Invalid pagination or unsupported query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"401":{"description":"API key missing, invalid, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"403":{"description":"Team subscription is not eligible for the public API","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"404":{"description":"Contact, site or LinkedIn profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"429":{"description":"100 requests per minute per team exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}},"headers":{"Retry-After":{"description":"Seconds until the next minute","schema":{"type":"integer"}}}},"503":{"description":"Public API rate limiter is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}}}}},"/interactions":{"get":{"summary":"List LinkedIn interactions","description":"Non-deleted interactions owned by the default site’s LinkedIn portability profile, with resolved actor names and matching own-post URLs, newest first.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"description":"Paginated results","content":{"application/json":{"schema":{"type":"object","required":["total","limit","skip","data"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Interaction"}}}}}}},"400":{"description":"Invalid pagination or unsupported query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"401":{"description":"API key missing, invalid, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"403":{"description":"Team subscription is not eligible for the public API","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"404":{"description":"Contact, site or LinkedIn profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"429":{"description":"100 requests per minute per team exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}},"headers":{"Retry-After":{"description":"Seconds until the next minute","schema":{"type":"integer"}}}},"503":{"description":"Public API rate limiter is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}}}}},"/posts":{"get":{"summary":"List LinkedIn posts","description":"Non-ad posts from the default site’s LinkedIn profile with their latest per-post analytics snapshot and classifier fields, newest first.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"description":"Paginated results","content":{"application/json":{"schema":{"type":"object","required":["total","limit","skip","data"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}}}}},"400":{"description":"Invalid pagination or unsupported query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"401":{"description":"API key missing, invalid, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"403":{"description":"Team subscription is not eligible for the public API","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"404":{"description":"Contact, site or LinkedIn profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"429":{"description":"100 requests per minute per team exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}},"headers":{"Retry-After":{"description":"Seconds until the next minute","schema":{"type":"integer"}}}},"503":{"description":"Public API rate limiter is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}}}}},"/messages":{"get":{"summary":"List LinkedIn direct messages","description":"Non-deleted messages involving the default site’s LinkedIn profile, with matching participant IDs and resolved names, newest first.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"description":"Paginated results","content":{"application/json":{"schema":{"type":"object","required":["total","limit","skip","data"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Dm"}}}}}}},"400":{"description":"Invalid pagination or unsupported query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"401":{"description":"API key missing, invalid, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"403":{"description":"Team subscription is not eligible for the public API","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"404":{"description":"Contact, site or LinkedIn profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"429":{"description":"100 requests per minute per team exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}},"headers":{"Retry-After":{"description":"Seconds until the next minute","schema":{"type":"integer"}}}},"503":{"description":"Public API rate limiter is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}}}}},"/activity":{"get":{"summary":"List LinkedIn activity","description":"Daily values for the six performance dashboard charts for the team’s default site, newest first.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":1000000,"default":0}}],"responses":{"200":{"description":"Paginated results","content":{"application/json":{"schema":{"type":"object","required":["total","limit","skip","data"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"skip":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Activity"}}}}}}},"400":{"description":"Invalid pagination or unsupported query parameter","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"401":{"description":"API key missing, invalid, expired or revoked","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"403":{"description":"Team subscription is not eligible for the public API","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"404":{"description":"Contact, site or LinkedIn profile not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}},"429":{"description":"100 requests per minute per team exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}},"headers":{"Retry-After":{"description":"Seconds until the next minute","schema":{"type":"integer"}}}},"503":{"description":"Public API rate limiter is temporarily unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"integer"}}}}}}}}}}}