{"openapi":"3.1.0","info":{"title":"bah.is API","description":"URL shortener API — create links, track analytics, manage domains, and more.","version":"1.0.0","contact":{"email":"hello@bah.is","url":"https://bah.is"}},"servers":[{"url":"https://api.bah.is","description":"Production"}],"security":[{"sessionCookie":[]},{"bearerAuth":[]}],"components":{"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"session","description":"Session cookie set after OAuth login"},"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (bah_xxxx) for programmatic access (Enterprise plan)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"data":{"type":"null"},"meta":{"type":"null"}}},"Link":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"shortUrl":{"type":"string"},"destination":{"type":"string"},"domain":{"type":"string"},"title":{"type":"string","nullable":true},"click_count":{"type":"integer"},"is_active":{"type":"integer"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}},"paths":{"/health":{"get":{"summary":"Health check","tags":["System"],"security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"example":{"status":"ok","service":"api.bah.is"}}}}}}},"/v1/links":{"get":{"summary":"List links","tags":["Links"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of links with pagination"},"401":{"description":"Authentication required"}}},"post":{"summary":"Create a short link","tags":["Links"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Destination URL","example":"https://example.com/my-page"},"slug":{"type":"string","description":"Custom slug (optional)","example":"my-link"},"title":{"type":"string","description":"Link title (optional)","example":"My Link"},"domain":{"type":"string","description":"Custom domain (optional, Pro only)","example":"links.myco.com"}}}}}},"responses":{"201":{"description":"Link created","content":{"application/json":{"example":{"data":{"id":"abc123","slug":"my-link","shortUrl":"https://bah.is/my-link","destination":"https://example.com/my-page","title":"My Link"},"error":null,"meta":null}}}},"400":{"description":"Invalid URL or slug"},"409":{"description":"Slug already taken"},"429":{"description":"Rate limit exceeded"}}}},"/v1/links/{id}":{"get":{"summary":"Get link details","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link details"},"404":{"description":"Link not found"}}},"put":{"summary":"Update a link","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}}}}}},"responses":{"200":{"description":"Link updated"},"404":{"description":"Link not found"}}},"delete":{"summary":"Delete a link","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link deleted"},"404":{"description":"Link not found"}}}},"/v1/links/{id}/qr":{"get":{"summary":"Get QR code for a link","tags":["Links"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"QR code SVG","content":{"image/svg+xml":{}}}}}},"/v1/me":{"get":{"summary":"Get current user profile","tags":["User"],"responses":{"200":{"description":"User profile","content":{"application/json":{"example":{"data":{"id":"abc","email":"user@example.com","name":"John","plan":"pro"}}}}}}}},"/v1/me/consents":{"patch":{"summary":"Update marketing consent","tags":["User"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"marketing":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Consent updated"}}}},"/v1/analytics/overview":{"get":{"summary":"Get analytics overview","tags":["Analytics"],"parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["24h","7d","30d","90d","1y","all"]}},{"name":"compare","in":"query","schema":{"type":"boolean"}},{"name":"linkId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Analytics data (locked for Free plan)"}}}},"/v1/analytics/realtime":{"get":{"summary":"Get real-time click feed","tags":["Analytics"],"description":"Last 20 clicks in real-time. Pro plan only.","responses":{"200":{"description":"Real-time click events"}}}},"/v1/analytics/link/{id}":{"get":{"summary":"Get analytics for a specific link","tags":["Analytics"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"period","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Link-specific analytics"}}}},"/v1/analytics/export":{"get":{"summary":"Export analytics data","tags":["Analytics"],"description":"Download analytics as CSV or JSON. Pro plan only.","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json"]}},{"name":"period","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Downloaded file"}}}},"/v1/domains":{"get":{"summary":"List custom domains","tags":["Domains"],"description":"Pro plan only.","responses":{"200":{"description":"List of domains"}}},"post":{"summary":"Add a custom domain","tags":["Domains"],"description":"Pro plan only. Limit: 1 domain.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","example":"links.myco.com"}}}}}},"responses":{"201":{"description":"Domain created with DNS instructions"},"403":{"description":"Pro plan required"}}}},"/v1/domains/{id}/verify":{"get":{"summary":"Check domain verification status","tags":["Domains"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current status"}}}},"/v1/domains/{id}":{"delete":{"summary":"Delete a custom domain","tags":["Domains"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Domain deleted"}}}},"/v1/buckets":{"get":{"summary":"List link buckets","tags":["Buckets"],"description":"Pro plan only.","responses":{"200":{"description":"List of buckets"}}},"post":{"summary":"Create a link bucket","tags":["Buckets"],"description":"Bundle up to 10 links under one short URL. Pro plan only.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","links"],"properties":{"name":{"type":"string","example":"Resources"},"slug":{"type":"string","example":"resources"},"links":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"}}},"maxItems":10}}}}}},"responses":{"201":{"description":"Bucket created"}}}},"/v1/keys":{"get":{"summary":"List API keys","tags":["API Keys"],"description":"Enterprise plan only.","responses":{"200":{"description":"List of API keys (prefix only)"}}},"post":{"summary":"Create an API key","tags":["API Keys"],"description":"Enterprise plan only. Full key shown once.","responses":{"201":{"description":"API key created"}}}},"/v1/keys/{id}":{"delete":{"summary":"Revoke an API key","tags":["API Keys"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked"}}}}},"tags":[{"name":"System","description":"Health and status"},{"name":"Links","description":"Create, read, update, delete short links"},{"name":"User","description":"User profile and consent management"},{"name":"Analytics","description":"Click analytics, real-time feed, export"},{"name":"Domains","description":"Custom domain management (Pro)"},{"name":"Buckets","description":"Link buckets — multiple links in one URL (Pro)"},{"name":"API Keys","description":"Programmatic access keys (Enterprise)"}]}