{"openapi":"3.1.0","info":{"title":"OBAOL Integration API","version":"1.0.0","description":"Operator-scoped REST API. Never expose API keys in browser source or public repositories."},"servers":[{"url":"/v1"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}},"x-scopes":["leads:read","leads:write","campaigns:read","campaigns:write","campaigns:control","sequences:read","reports:read"],"paths":{"/auth/check":{"get":{"summary":"Verify a key and inspect effective scopes","tags":["auth"],"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"key_id":{"type":"string"},"operator_id":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/leads":{"get":{"summary":"List leads","tags":["leads"],"x-required-scope":"leads:read","security":[{"ApiKey":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"lead_status":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}},"post":{"summary":"Create a lead","tags":["leads"],"x-required-scope":"leads:write","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"country":{"type":"string"},"job_title":{"type":"string"},"phone":{"type":"string"},"linkedin_url":{"type":"string"},"website":{"type":"string"},"industry":{"type":"string"},"source":{"type":"string"},"notes":{"type":"string"},"lead_status":{"type":"string"}},"required":["email"],"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":128},"description":"Optional retry-safe request key."}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"lead_status":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/leads/{id}":{"get":{"summary":"Read a lead","tags":["leads"],"x-required-scope":"leads:read","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"lead_status":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}},"patch":{"summary":"Update a lead","tags":["leads"],"x-required-scope":"leads:write","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"country":{"type":"string"},"job_title":{"type":"string"},"phone":{"type":"string"},"linkedin_url":{"type":"string"},"website":{"type":"string"},"industry":{"type":"string"},"source":{"type":"string"},"notes":{"type":"string"},"lead_status":{"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"lead_status":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a lead","tags":["leads"],"x-required-scope":"leads:write","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/campaigns":{"get":{"summary":"List campaigns","tags":["campaigns"],"x-required-scope":"campaigns:read","security":[{"ApiKey":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sequence_id":{"type":"string"},"status":{"type":"string"},"sender_display_name":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}},"post":{"summary":"Create a campaign","tags":["campaigns"],"x-required-scope":"campaigns:write","security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"sequence_id":{"type":"string"},"sender_display_name":{"type":"string"}},"required":["name","sequence_id"],"additionalProperties":false}}}},"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":128},"description":"Optional retry-safe request key."}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sequence_id":{"type":"string"},"status":{"type":"string"},"sender_display_name":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/campaigns/{id}":{"get":{"summary":"Read a campaign","tags":["campaigns"],"x-required-scope":"campaigns:read","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sequence_id":{"type":"string"},"status":{"type":"string"},"sender_display_name":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}},"patch":{"summary":"Update a campaign","tags":["campaigns"],"x-required-scope":"campaigns:write","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"sequence_id":{"type":"string"},"sender_display_name":{"type":"string"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sequence_id":{"type":"string"},"status":{"type":"string"},"sender_display_name":{"type":"string"},"created_at":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/campaigns/{id}/leads":{"post":{"summary":"Assign leads to a campaign","tags":["campaigns"],"x-required-scope":"campaigns:write","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":128},"description":"Optional retry-safe request key."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_ids":{"type":"array","items":{"type":"string"}}},"required":["lead_ids"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"requested":{"type":"integer"},"inserted":{"type":"integer"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/campaigns/{id}/start":{"post":{"summary":"Start a campaign","tags":["campaigns"],"x-required-scope":"campaigns:control","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":128},"description":"Optional retry-safe request key."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/campaigns/{id}/pause":{"post":{"summary":"Pause a campaign","tags":["campaigns"],"x-required-scope":"campaigns:control","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","minLength":8,"maxLength":128},"description":"Optional retry-safe request key."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/campaigns/{id}/status":{"get":{"summary":"Read campaign status","tags":["campaigns"],"x-required-scope":"campaigns:read","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/campaigns/{id}/report":{"get":{"summary":"Read campaign lead counts","tags":["reports"],"x-required-scope":"reports:read","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"campaign_id":{"type":"string"},"total_leads":{"type":"integer"},"by_status":{"type":"object"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/sequences":{"get":{"summary":"List sequences used by this operator","tags":["sequences"],"x-required-scope":"sequences:read","security":[{"ApiKey":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/sequences/{id}":{"get":{"summary":"Read a sequence used by this operator","tags":["sequences"],"x-required-scope":"sequences:read","security":[{"ApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}},"/reports/overview":{"get":{"summary":"Read operator overview counts","tags":["reports"],"x-required-scope":"reports:read","security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"leads":{"type":"integer"},"campaigns":{"type":"integer"},"campaign_leads":{"type":"integer"}},"additionalProperties":false}}}},"default":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string"}}}}}}}}}}}