{"openapi":"3.0.3","info":{"title":"Bridgly Developer API","version":"1.0.0","description":"Project-scoped HTTP API for partner attribution and stats.\nNo SDK required — use Bearer `ak_live_…` keys from Workspace settings → API keys.\nMachine-readable twin: GET /openapi.json\n"},"servers":[{"url":"https://www.bridgly.co","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Stats"},{"name":"Links"},{"name":"Partners"},{"name":"Payouts"},{"name":"Conversions"},{"name":"Track"}],"paths":{"/api/v1/stats/summary":{"get":{"tags":["Stats"],"summary":"Project click/lead/sale summary","operationId":"getStatsSummary","responses":{"200":{"description":"Project summary","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/ProjectRef"},"clicks":{"type":"integer"},"leads":{"type":"integer"},"sales":{"type":"integer"},"revenueCents":{"type":"integer"},"currency":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/stats/funnel":{"get":{"tags":["Stats"],"summary":"Workspace conversion funnel","operationId":"getStatsFunnel","responses":{"200":{"description":"Workspace funnel","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid"},"clicks":{"type":"integer"},"leads":{"type":"integer"},"sales":{"type":"integer"},"revenueCents":{"type":"integer"},"currency":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/links":{"get":{"tags":["Links"],"summary":"List short links for the key’s project","operationId":"listLinks","parameters":[{"in":"query","name":"projectId","required":false,"schema":{"type":"string","format":"uuid"},"description":"Filter to one project (link/app). Omit for the whole workspace."}],"responses":{"200":{"description":"Links with click counts","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid"},"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Links"],"summary":"Create a short link on the key’s project","operationId":"createLink","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLinkBody"}}}},"responses":{"201":{"description":"Link created","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CreatedLink"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/payouts/summary":{"get":{"tags":["Payouts"],"summary":"Workspace partner payout balances","operationId":"getPayoutsSummary","responses":{"200":{"description":"Per-partner and total balances","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid"},"setupRequired":{"type":"boolean"},"totals":{"$ref":"#/components/schemas/BalanceTotals"},"partners":{"type":"array","items":{"$ref":"#/components/schemas/PartnerBalance"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/conversions":{"get":{"tags":["Conversions"],"summary":"Recent project conversions","operationId":"listConversions","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"before","in":"query","description":"ISO created_at cursor from previous nextBefore","schema":{"type":"string","format":"date-time"}},{"name":"type","in":"query","schema":{"type":"string","enum":["lead","sale"]}}],"responses":{"200":{"description":"Conversion page","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid"},"conversions":{"type":"array","items":{"$ref":"#/components/schemas/Conversion"}},"nextBefore":{"type":"string","format":"date-time","nullable":true},"limit":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/partners":{"get":{"tags":["Partners"],"summary":"List partners (referrers) for the key’s workspace","operationId":"listPartners","responses":{"200":{"description":"Partners list","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"workspaceId":{"type":"string","format":"uuid"},"partners":{"type":"array","items":{"$ref":"#/components/schemas/Partner"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/partners/{id}/stats":{"get":{"tags":["Partners"],"summary":"Partner-level clicks, leads, sales","operationId":"getPartnerStats","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Partner stats","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"partner":{"$ref":"#/components/schemas/PartnerRef"},"stats":{"$ref":"#/components/schemas/StatsBlock"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/track/lead":{"post":{"tags":["Track"],"summary":"Track a lead conversion","operationId":"trackLead","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackLeadBody"}}}},"responses":{"200":{"description":"Lead recorded (or duplicate)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackLeadResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/track/sale":{"post":{"tags":["Track"],"summary":"Track a sale conversion","operationId":"trackSale","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackSaleBody"}}}},"responses":{"200":{"description":"Sale recorded (or duplicate)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackSaleResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ak_live_","description":"Project API key from Workspace settings → API keys"}},"schemas":{"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"ProjectRef":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"Link":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"clicks":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"CreatedLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"url":{"type":"string"},"clicks":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"CreateLinkBody":{"type":"object","required":["destinations"],"properties":{"slug":{"type":"string"},"destinations":{"type":"object","properties":{"web":{"type":"string"},"ios":{"type":"string"},"android":{"type":"string"}}},"expiresAt":{"type":"string","format":"date-time"},"domainId":{"type":"string","format":"uuid"}}},"BalanceTotals":{"type":"object","properties":{"availableCents":{"type":"integer"},"heldCents":{"type":"integer"},"payableCents":{"type":"integer"},"currency":{"type":"string"}}},"PartnerBalance":{"type":"object","properties":{"referrerId":{"type":"string","format":"uuid"},"name":{"type":"string"},"code":{"type":"string"},"availableCents":{"type":"integer"},"heldCents":{"type":"integer"},"payableCents":{"type":"integer"},"currency":{"type":"string"}}},"Conversion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"eventName":{"type":"string"},"amountCents":{"type":"integer","nullable":true},"currency":{"type":"string","nullable":true},"customerExternalId":{"type":"string","nullable":true},"invoiceId":{"type":"string","nullable":true},"referrerId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Partner":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","nullable":true},"code":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"PartnerRef":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"}}},"StatsBlock":{"type":"object","properties":{"clicks":{"type":"integer"},"leads":{"type":"integer"},"sales":{"type":"integer"},"revenueCents":{"type":"integer"},"currency":{"type":"string"}}},"TrackLeadBody":{"type":"object","required":["customerExternalId","eventName"],"properties":{"customerExternalId":{"type":"string"},"eventName":{"type":"string"},"clickId":{"type":"string","format":"uuid"},"storeSessionId":{"type":"string","format":"uuid"},"bridgly_session_id":{"type":"string","format":"uuid"},"referrerId":{"type":"string","format":"uuid","description":"Attribute directly to a partner (person or agent_surface)"},"referralCode":{"type":"string","description":"Partner code when no click/session (e.g. agent checkout)"},"agentId":{"type":"string","description":"Non-human referrer identity"},"agentSurface":{"type":"string","description":"Surface label (e.g. chatgpt, brand_chatbot)"},"agentProtocol":{"type":"string","description":"acp | ucp | visa_tap | other"},"metadata":{"type":"object","additionalProperties":true}}},"TrackSaleBody":{"type":"object","required":["customerExternalId","eventName"],"properties":{"customerExternalId":{"type":"string"},"eventName":{"type":"string"},"amountCents":{"type":"integer","description":"Preferred amount in cents"},"amount":{"type":"integer","description":"Alias for amountCents"},"currency":{"type":"string","example":"usd"},"invoiceId":{"type":"string"},"paymentProcessor":{"type":"string"},"clickId":{"type":"string","format":"uuid"},"storeSessionId":{"type":"string","format":"uuid"},"bridgly_session_id":{"type":"string","format":"uuid"},"referrerId":{"type":"string","format":"uuid","description":"Attribute directly to a partner (person or agent_surface)"},"referralCode":{"type":"string"},"agentId":{"type":"string"},"agentSurface":{"type":"string"},"agentProtocol":{"type":"string","description":"acp | ucp | visa_tap | other"},"metadata":{"type":"object","additionalProperties":true}}},"TrackLeadResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"conversionId":{"type":"string","nullable":true},"clickId":{"type":"string","nullable":true},"referrerId":{"type":"string","nullable":true},"duplicate":{"type":"boolean"}}},"TrackSaleResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"conversionId":{"type":"string","nullable":true},"clickId":{"type":"string","nullable":true},"referrerId":{"type":"string","nullable":true},"duplicate":{"type":"boolean"},"commissionCents":{"type":"integer","nullable":true}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"Forbidden":{"description":"Self-referral blocked or other policy denial","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"Error":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"RateLimited":{"description":"More than 120 requests per minute per project (shared across /api/v1 and /api/track); honor Retry-After","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}}