{"openapi":"3.1.0","info":{"title":"HookFlow API","description":"Receive, transform, and route webhooks. Authenticate with a Bearer access token from /api/v1/auth/token or a workspace API key.","version":"2.4.1"},"paths":{"/api/v1/health":{"get":{"tags":["Service"],"summary":"Liveness probe","operationId":"health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/status":{"get":{"tags":["Service"],"summary":"Platform status","operationId":"status_api_v1_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/version":{"get":{"tags":["Service"],"summary":"API build info","operationId":"version_api_v1_version_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/regions":{"get":{"tags":["Service"],"summary":"Ingestion regions","operationId":"regions_api_v1_regions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/audit-log":{"get":{"tags":["Audit"],"summary":"Recent account activity","operationId":"audit_log_api_v1_audit_log_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/hooks/stripe":{"post":{"tags":["Ingestion"],"summary":"Receive Stripe webhook","description":"Accept a Stripe webhook and queue it for delivery.","operationId":"receive_stripe_hooks_stripe_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/hooks/github":{"post":{"tags":["Ingestion"],"summary":"Receive Github webhook","description":"Accept a Github webhook and queue it for delivery.","operationId":"receive_github_hooks_github_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/hooks/shopify":{"post":{"tags":["Ingestion"],"summary":"Receive Shopify webhook","description":"Accept a Shopify webhook and queue it for delivery.","operationId":"receive_shopify_hooks_shopify_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/hooks/twilio":{"post":{"tags":["Ingestion"],"summary":"Receive Twilio webhook","description":"Accept a Twilio webhook and queue it for delivery.","operationId":"receive_twilio_hooks_twilio_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/hooks/sendgrid":{"post":{"tags":["Ingestion"],"summary":"Receive Sendgrid webhook","description":"Accept a Sendgrid webhook and queue it for delivery.","operationId":"receive_sendgrid_hooks_sendgrid_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/hooks/custom/{token}":{"post":{"tags":["Ingestion"],"summary":"Receive custom webhook","description":"Accept any JSON payload. If `token` matches an endpoint, the delivery is attached to it.","operationId":"receive_custom_hooks_custom__token__post","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/endpoints":{"get":{"tags":["Endpoints"],"summary":"List endpoints","operationId":"list_endpoints_api_v1_endpoints_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["active","paused","failing"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"provider","in":"query","required":false,"schema":{"anyOf":[{"enum":["stripe","github","shopify","twilio","sendgrid","custom"],"type":"string"},{"type":"null"}],"title":"Provider"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Endpoints"],"summary":"Create endpoint","operationId":"create_endpoint_api_v1_endpoints_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/endpoints/{endpoint_id}":{"get":{"tags":["Endpoints"],"summary":"Get endpoint","operationId":"get_endpoint_api_v1_endpoints__endpoint_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Endpoints"],"summary":"Replace endpoint","operationId":"replace_endpoint_api_v1_endpoints__endpoint_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Endpoints"],"summary":"Update endpoint fields","operationId":"patch_endpoint_api_v1_endpoints__endpoint_id__patch","security":[{"HTTPBearer":[]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndpointUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Endpoints"],"summary":"Delete endpoint","operationId":"delete_endpoint_api_v1_endpoints__endpoint_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/endpoints/{endpoint_id}/deliveries":{"get":{"tags":["Endpoints"],"summary":"Deliveries for an endpoint","operationId":"endpoint_deliveries_api_v1_endpoints__endpoint_id__deliveries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["200","500","timeout"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/endpoints/{endpoint_id}/test":{"post":{"tags":["Endpoints"],"summary":"Send a test event","description":"Simulates a delivery to the endpoint URL and records the result.","operationId":"test_endpoint_api_v1_endpoints__endpoint_id__test_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string","title":"Endpoint Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/deliveries":{"get":{"tags":["Deliveries"],"summary":"List deliveries across all endpoints","operationId":"list_deliveries_api_v1_deliveries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["200","500","timeout"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Unix timestamp, inclusive","title":"Since"},"description":"Unix timestamp, inclusive"},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Unix timestamp, inclusive","title":"Until"},"description":"Unix timestamp, inclusive"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/transforms":{"get":{"tags":["Transformations"],"summary":"List transformations","operationId":"list_transforms_api_v1_transforms_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["Transformations"],"summary":"Create transformation","operationId":"create_transform_api_v1_transforms_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransformCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/transforms/{transform_id}":{"get":{"tags":["Transformations"],"summary":"Get transformation","operationId":"get_transform_api_v1_transforms__transform_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"transform_id","in":"path","required":true,"schema":{"type":"string","title":"Transform Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Transformations"],"summary":"Replace transformation","operationId":"update_transform_api_v1_transforms__transform_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"transform_id","in":"path","required":true,"schema":{"type":"string","title":"Transform Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransformCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Transformations"],"summary":"Delete transformation","operationId":"delete_transform_api_v1_transforms__transform_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"transform_id","in":"path","required":true,"schema":{"type":"string","title":"Transform Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/transforms/{transform_id}/preview":{"post":{"tags":["Transformations"],"summary":"Run a transformation against a sample payload","operationId":"preview_transform_api_v1_transforms__transform_id__preview_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"transform_id","in":"path","required":true,"schema":{"type":"string","title":"Transform Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metrics/summary":{"get":{"tags":["Metrics"],"summary":"Delivery totals for a period","operationId":"summary_api_v1_metrics_summary_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","examples":["24h","7d"],"default":"24h","title":"Period"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metrics/timeseries":{"get":{"tags":["Metrics"],"summary":"Bucketed time series","operationId":"timeseries_api_v1_metrics_timeseries_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"metric","in":"query","required":false,"schema":{"enum":["deliveries","errors","latency"],"type":"string","default":"deliveries","title":"Metric"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","examples":["24h","7d"],"default":"7d","title":"Period"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metrics/top-errors":{"get":{"tags":["Metrics"],"summary":"Most frequent failures by endpoint","operationId":"top_errors_api_v1_metrics_top_errors_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","default":"7d","title":"Period"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":5,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/register":{"post":{"tags":["Auth"],"summary":"Create an account","operationId":"register_api_v1_auth_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/token":{"post":{"tags":["Auth"],"summary":"Exchange credentials for a token","operationId":"issue_token_api_v1_auth_token_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/refresh":{"post":{"tags":["Auth"],"summary":"Refresh an access token","operationId":"refresh_token_api_v1_auth_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/auth/me":{"get":{"tags":["Auth"],"summary":"Current principal","operationId":"me_api_v1_auth_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/keys":{"get":{"tags":["API keys"],"summary":"List API keys","operationId":"list_keys_api_v1_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["API keys"],"summary":"Create API key","operationId":"create_key_api_v1_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCreate"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/keys/{key_id}":{"delete":{"tags":["API keys"],"summary":"Revoke API key","operationId":"delete_key_api_v1_keys__key_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"EndpointCreate":{"properties":{"name":{"type":"string","maxLength":64,"minLength":2,"pattern":"^[a-z0-9][a-z0-9\\-]*$","title":"Name","examples":["billing-events"]},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url","examples":["https://api.example.com/webhooks"]},"provider":{"type":"string","enum":["stripe","github","shopify","twilio","sendgrid","custom"],"title":"Provider","default":"custom"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"},"status":{"type":"string","enum":["active","paused","failing"],"title":"Status","default":"active"}},"type":"object","required":["name","url"],"title":"EndpointCreate"},"EndpointUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":64,"minLength":2,"pattern":"^[a-z0-9][a-z0-9\\-]*$"},{"type":"null"}],"title":"Name"},"url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Url"},"provider":{"anyOf":[{"type":"string","enum":["stripe","github","shopify","twilio","sendgrid","custom"]},{"type":"null"}],"title":"Provider"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"},"status":{"anyOf":[{"type":"string","enum":["active","paused","failing"]},{"type":"null"}],"title":"Status"}},"type":"object","title":"EndpointUpdate"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"KeyCreate":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name","examples":["Staging server"]}},"type":"object","required":["name"],"title":"KeyCreate"},"PreviewRequest":{"properties":{"payload":{"title":"Payload","examples":[{"data":{"object":{"amount":2900,"customer":"cus_42"}}}]}},"type":"object","required":["payload"],"title":"PreviewRequest"},"RefreshRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token"}},"type":"object","required":["refresh_token"],"title":"RefreshRequest"},"RegisterRequest":{"properties":{"name":{"type":"string","maxLength":80,"minLength":2,"title":"Name","examples":["Ada Lovelace"]},"email":{"type":"string","maxLength":160,"title":"Email","examples":["ada@example.com"]},"password":{"type":"string","maxLength":128,"minLength":8,"title":"Password"}},"type":"object","required":["name","email","password"],"title":"RegisterRequest"},"TokenRequest":{"properties":{"email":{"type":"string","title":"Email","examples":["ada@example.com"]},"password":{"type":"string","minLength":1,"title":"Password"}},"type":"object","required":["email","password"],"title":"TokenRequest"},"TransformCreate":{"properties":{"name":{"type":"string","maxLength":100,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"},"endpoint_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint Id"},"mapping":{"additionalProperties":{"type":"string"},"type":"object","title":"Mapping","description":"Output field → dotted path (`items.0.sku`).","examples":[{"amount":"data.object.amount","customer":"data.object.customer"}]},"enabled":{"type":"boolean","title":"Enabled","default":true}},"type":"object","required":["name","mapping"],"title":"TransformCreate"},"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","description":"Access token from /auth/token, or an API key (hf_live_...).","scheme":"bearer"}}}}