{"openapi":"3.1.0","info":{"title":"Project Synapse Developer API","version":"v1"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Problem":{"type":"object","required":["type","title","status","code"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}}},"Developer":{"type":"object","required":["id","email","name","polarCustomerId"],"properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"polarCustomerId":{"type":["string","null"]}}},"ApiKey":{"type":"object","required":["id","name","environment","scopes","createdAt"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"environment":{"enum":["test","production"]},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"},"revokedAt":{"type":["string","null"],"format":"date-time"}}},"ApiKeyPage":{"type":"object","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"Holiday":{"type":"object","required":["date","name","localName","nationwide"],"properties":{"date":{"type":"string","format":"date"},"name":{"type":"string"},"localName":{"type":"string"},"nationwide":{"type":"boolean"}}},"SnapshotMeta":{"type":"object","required":["source","generatedAt","sample","limitations"],"properties":{"source":{"type":"string"},"generatedAt":{"type":"string","format":"date"},"sample":{"type":"boolean"},"limitations":{"type":"array","items":{"type":"string"}}}},"HolidaysResponse":{"type":"object","required":["country","year","holidays","coverage"],"properties":{"country":{"type":"string"},"year":{"type":"integer"},"holidays":{"type":"array","items":{"$ref":"#/components/schemas/Holiday"}},"coverage":{"$ref":"#/components/schemas/SnapshotMeta"}}},"BusinessDay":{"type":"object","required":["date","businessDay","reason"],"properties":{"date":{"type":"string","format":"date"},"businessDay":{"type":"boolean"},"reason":{"type":["string","null"],"enum":["weekend","holiday",null]}}},"WorkingHoursShift":{"type":"object","required":["from","days","date"],"properties":{"from":{"type":"string","format":"date"},"days":{"type":"integer"},"date":{"type":"string","format":"date"}}},"WorkingHoursBetween":{"type":"object","required":["from","to","businessDays"],"properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"businessDays":{"type":"integer"}}},"EmailVerification":{"type":"object","required":["email","domain","tier","reason","signals"],"properties":{"email":{"type":"string"},"domain":{"type":["string","null"]},"tier":{"enum":["valid","risky","unknown","invalid"]},"reason":{"enum":["invalid_syntax","no_mx","mx_lookup_failed","disposable_domain","role_account","mailbox_unverified"]},"signals":{"type":"object","required":["syntaxValid","hasMx","disposableDomain","freeProvider","roleAccount"],"properties":{"syntaxValid":{"type":"boolean"},"hasMx":{"type":"boolean"},"disposableDomain":{"type":"boolean"},"freeProvider":{"type":"boolean"},"roleAccount":{"type":"boolean"}}}}}}},"paths":{"/v1":{"get":{"responses":{"200":{"description":"API version metadata"}}}},"/v1/developers":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","name"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"polarCustomerId":{"type":["string","null"]}}}}}},"responses":{"201":{"description":"Developer account created","content":{"application/json":{"schema":{"type":"object","required":["developer"],"properties":{"developer":{"$ref":"#/components/schemas/Developer"}}}}}},"409":{"description":"Idempotency conflict"},"422":{"description":"Invalid request"}}}},"/v1/developers/{developerId}/api-keys":{"get":{"parameters":[{"name":"developerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyPage"}}}}}},"post":{"parameters":[{"name":"developerId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string"},"environment":{"enum":["test","production"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"API key created (the secret `key` is returned once)","content":{"application/json":{"schema":{"type":"object","required":["apiKey"],"properties":{"apiKey":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","required":["key"],"properties":{"key":{"type":"string"}}}]}}}}}},"422":{"description":"Invalid request"}}}},"/v1/developers/{developerId}/api-keys/{keyId}":{"patch":{"parameters":[{"name":"developerId","in":"path","required":true,"schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expiresAt"],"properties":{"expiresAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"API key updated","content":{"application/json":{"schema":{"type":"object","required":["apiKey"],"properties":{"apiKey":{"$ref":"#/components/schemas/ApiKey"}}}}}}}},"delete":{"parameters":[{"name":"developerId","in":"path","required":true,"schema":{"type":"string"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key revoked"}}}},"/v1/email/verify":{"post":{"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}}}},"responses":{"200":{"description":"Workers-native verification tier. `valid` is never returned here (it requires an SMTP probe); honest tiers are invalid/risky/unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerification"}}}},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient scope"},"422":{"description":"Missing or malformed request body"},"429":{"description":"Rate or quota limited"}}}},"/v1/holidays/{country}/{year}":{"get":{"security":[{"BearerAuth":[]}],"parameters":[{"name":"country","in":"path","required":true,"description":"ISO-3166-1 alpha-2 country code.","schema":{"type":"string"}},{"name":"year","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Public holidays for the country and year","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidaysResponse"}}}},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient scope"},"404":{"description":"Country or year not covered by the snapshot","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate or quota limited"}}}},"/v1/working-hours/{country}/business-day":{"get":{"security":[{"BearerAuth":[]}],"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","required":true,"description":"Date to test, YYYY-MM-DD.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Whether the date is a working day","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessDay"}}}},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient scope"},"404":{"description":"Country or year not covered"},"422":{"description":"Invalid date"},"429":{"description":"Rate or quota limited"}}}},"/v1/working-hours/{country}/shift":{"get":{"security":[{"BearerAuth":[]}],"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","required":true,"description":"Start date, YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"days","in":"query","required":true,"description":"Business days to add (negative walks backwards).","schema":{"type":"integer"}}],"responses":{"200":{"description":"The date shifted by N business days","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkingHoursShift"}}}},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient scope"},"404":{"description":"Country or year not covered"},"422":{"description":"Invalid date or amount"},"429":{"description":"Rate or quota limited"}}}},"/v1/working-hours/{country}/between":{"get":{"security":[{"BearerAuth":[]}],"parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":true,"description":"Range start (inclusive), YYYY-MM-DD.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Range end (inclusive), YYYY-MM-DD.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Count of business days in the inclusive range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkingHoursBetween"}}}},"401":{"description":"Invalid API key"},"403":{"description":"Insufficient scope"},"404":{"description":"Country or year not covered"},"422":{"description":"Invalid date or range"},"429":{"description":"Rate or quota limited"}}}},"/v1/whoami":{"get":{"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Authenticated API key context"},"401":{"description":"Invalid API key"}}}}}}