{"openapi":"3.0.0","info":{"title":"CustomerOS API","version":"1.0.0","description":"API for managing customer engagement flows and sequences"},"servers":[{"url":"https://api.customeros.ai/flow/{version}","variables":{"version":{"default":"v1"}}}],"paths":{"/flows":{"get":{"summary":"List all flows","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowList"}}}}}},"post":{"summary":"Create a new flow","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowCreate"}}}},"responses":{"201":{"description":"Successfully created flow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}}}}},"/flows/{flow_id}":{"get":{"summary":"Get details of a specific flow","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}}}},"patch":{"summary":"Update details of a specific flow","parameters":[{"$ref":"#/components/parameters/flow_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowUpdate"}}}},"responses":{"200":{"description":"Successfully updated flow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flow"}}}}}},"delete":{"summary":"Delete a specific flow","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"204":{"description":"Successfully deleted flow"}}}},"/flows/{flow_id}/enable":{"get":{"summary":"Enable a flow","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successfully enabled flow"}}}},"/flows/{flow_id}/disable":{"get":{"summary":"Disable a flow","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successfully disabled flow"}}}},"/flows/{flow_id}/stats":{"get":{"summary":"Get stats for a flow","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/flows/{flow_id}/sequences":{"get":{"summary":"List all sequences","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SequenceList"}}}}}},"post":{"summary":"Create new sequence","parameters":[{"$ref":"#/components/parameters/flow_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SequenceCreate"}}}},"responses":{"201":{"description":"Successfully created sequence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sequence"}}}}}}},"/flows/{flow_id}/sequences/{sequence_id}":{"get":{"summary":"Get details of a specific sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sequence"}}}}}},"patch":{"summary":"Update details of a specific sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SequenceUpdate"}}}},"responses":{"200":{"description":"Successfully updated sequence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sequence"}}}}}},"delete":{"summary":"Delete a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"responses":{"204":{"description":"Successfully deleted sequence"}}}},"/flows/{flow_id}/sequences/{sequence_id}/enable":{"post":{"summary":"Enable a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"responses":{"200":{"description":"Successfully enabled sequence"}}}},"/flows/{flow_id}/sequences/{sequence_id}/disable":{"post":{"summary":"Disable a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"responses":{"200":{"description":"Successfully disabled sequence"}}}},"/flows/{flow_id}/sequences/{sequence_id}/stats":{"get":{"summary":"Get statistics for a specific sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/flows/{flow_id}/schedule":{"get":{"summary":"Get details of a specific sequence schedule","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Schedule"}}}}}},"put":{"summary":"Update details of a specific sequence schedule","parameters":[{"$ref":"#/components/parameters/flow_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleUpdate"}}}},"responses":{"200":{"description":"Successfully updated schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Schedule"}}}}}},"delete":{"summary":"Delete details of a specific sequence schedule","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"204":{"description":"Successfully deleted schedule"}}}},"/flows/{flow_id}/config":{"get":{"summary":"Get details of a specific sequence configuration","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Config"}}}}}},"put":{"summary":"Update details of a specific sequence configuration","parameters":[{"$ref":"#/components/parameters/flow_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigUpdate"}}}},"responses":{"200":{"description":"Successfully updated configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Config"}}}}}},"delete":{"summary":"Delete details of a specific sequence configuration","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"204":{"description":"Successfully deleted configuration"}}}},"/flows/{flow_id}/sequences/{sequence_id}/steps":{"get":{"summary":"List all steps for a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepList"}}}}}},"post":{"summary":"Add a step to a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepCreate"}}}},"responses":{"201":{"description":"Successfully created step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Step"}}}}}}},"/flows/{flow_id}/sequences/{sequence_id}/steps/{step_id}":{"get":{"summary":"List details for a step in a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"},{"$ref":"#/components/parameters/step_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Step"}}}}}},"put":{"summary":"Update a step in a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"},{"$ref":"#/components/parameters/step_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepUpdate"}}}},"responses":{"200":{"description":"Successfully updated step","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Step"}}}}}},"delete":{"summary":"Delete a step in a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"},{"$ref":"#/components/parameters/step_id"}],"responses":{"204":{"description":"Successfully deleted step"}}}},"/flows/{flow_id}/senders":{"get":{"summary":"List all senders for a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderList"}}}}}},"post":{"summary":"Add a sender to a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SenderCreate"}}}},"responses":{"201":{"description":"Successfully created sender","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sender"}}}}}}},"/flows/{flow_id}/senders/{sender_id}":{"delete":{"summary":"Remove sender from a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sender_id"}],"responses":{"204":{"description":"Successfully removed sender"}}}},"/flows/{flow_id}/sequences/{sequence_id}/contacts":{"get":{"summary":"List all contacts for a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}}}}},"post":{"summary":"Add contacts to a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactCreate"}}}},"responses":{"201":{"description":"Successfully added contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}}}}},"/flows/{flow_id}/sequences/{sequence_id}/contacts/{contact_id}":{"get":{"summary":"Get details of a specific contact in a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"},{"$ref":"#/components/parameters/contact_id"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}}}},"delete":{"summary":"Remove a contact from a sequence","parameters":[{"$ref":"#/components/parameters/flow_id"},{"$ref":"#/components/parameters/sequence_id"},{"$ref":"#/components/parameters/contact_id"}],"responses":{"204":{"description":"Successfully removed contact"}}}}},"components":{"parameters":{"flow_id":{"name":"flow_id","in":"path","required":true,"schema":{"type":"string"}},"sequence_id":{"name":"sequence_id","in":"path","required":true,"schema":{"type":"string"}},"step_id":{"name":"step_id","in":"path","required":true,"schema":{"type":"string"}},"sender_id":{"name":"sender_id","in":"path","required":true,"schema":{"type":"string"}},"contact_id":{"name":"contact_id","in":"path","required":true,"schema":{"type":"string"}}},"schemas":{"FlowList":{"type":"object","properties":{"flows":{"type":"array","items":{"$ref":"#/components/schemas/Flow"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Flow":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["active","draft"]},"sequenceCount":{"type":"integer"}}},"FlowCreate":{"type":"object","required":["name","status"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["active","draft"]}}},"FlowUpdate":{"type":"object","properties":{"name":{"type":"string"},"status":{"type":"string","enum":["active","draft"]}}},"SequenceList":{"type":"object","properties":{"sequences":{"type":"array","items":{"$ref":"#/components/schemas/Sequence"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Sequence":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["enabled","disabled"]},"personas":{"type":"array","items":{"type":"string"}},"stepCount":{"type":"integer"}}},"SequenceCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["enabled","disabled"]},"personas":{"type":"array","items":{"type":"string"}}}},"SequenceUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string","enum":["enabled","disabled"]},"personas":{"type":"array","items":{"type":"string"}}}},"Schedule":{"type":"object","properties":{"flowId":{"type":"string"},"schedule":{"type":"object","properties":{"activeDays":{"type":"array","items":{"type":"string","enum":["monday","tuesday","wednesday","thursday","friday","saturday","sunday"]}},"activeTimeWindow":{"type":"object","properties":{"start":{"type":"string","format":"time"},"end":{"type":"string","format":"time"}}},"pauseOnHolidays":{"type":"boolean"},"respectRecipientTimezone":{"type":"boolean"},"rules":{"type":"object","properties":{"minutesDelayBetweenEmails":{"type":"integer"}}},"limits":{"type":"object","properties":{"emailsPerMailboxPerHour":{"type":"integer"},"emailsPerMailboxPerDay":{"type":"integer"}}}}},"lastUpdated":{"type":"string","format":"date-time"}}},"ScheduleUpdate":{"type":"object","properties":{"schedule":{"$ref":"#/components/schemas/Schedule/properties/schedule"}}},"Config":{"type":"object","properties":{"flowId":{"type":"string"},"config":{"type":"object","properties":{"optOut":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":"string"}}},"analytics":{"type":"object","properties":{"trackEmailOpens":{"type":"boolean"},"trackLinkClicks":{"type":"object","properties":{"enabled":{"type":"boolean"},"useCustomDomain":{"type":"boolean"},"customDomain":{"type":"string"}}}}}}},"lastUpdated":{"type":"string","format":"date-time"}}},"ConfigUpdate":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/Config/properties/config"}}},"StepList":{"type":"object","properties":{"sequenceId":{"type":"string"},"sequenceName":{"type":"string"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/Step"}}}},"Step":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["email","linkedin","manual"]},"order":{"type":"integer"},"status":{"type":"string","enum":["enabled","disabled"]},"details":{"oneOf":[{"$ref":"#/components/schemas/EmailStepDetails"},{"$ref":"#/components/schemas/LinkedInStepDetails"},{"$ref":"#/components/schemas/ManualStepDetails"}]},"waitTime":{"type":"object","properties":{"duration":{"type":"integer"},"unit":{"type":"string","enum":["minutes","hours","days"]}}}}},"EmailStepDetails":{"type":"object","properties":{"subject":{"type":"string"},"body":{"type":"string"}}},"LinkedInStepDetails":{"type":"object","properties":{"actionType":{"type":"string","enum":["connection request","message"]},"message":{"type":"string"},"linkedinUrl":{"type":"string"}}},"ManualStepDetails":{"type":"object","properties":{"title":{"type":"string"},"body":{"type":"string"}}},"StepCreate":{"type":"object","required":["type","order","details","waitTime"],"properties":{"type":{"type":"string","enum":["email","linkedin","manual"]},"order":{"type":"integer"},"status":{"type":"string","enum":["enabled","disabled"]},"details":{"oneOf":[{"$ref":"#/components/schemas/EmailStepDetails"},{"$ref":"#/components/schemas/LinkedInStepDetails"},{"$ref":"#/components/schemas/ManualStepDetails"}]},"waitTime":{"$ref":"#/components/schemas/Step/properties/waitTime"}}},"StepUpdate":{"type":"object","properties":{"type":{"type":"string","enum":["email","linkedin","manual"]},"order":{"type":"integer"},"status":{"type":"string","enum":["enabled","disabled"]},"details":{"oneOf":[{"$ref":"#/components/schemas/EmailStepDetails"},{"$ref":"#/components/schemas/LinkedInStepDetails"},{"$ref":"#/components/schemas/ManualStepDetails"}]},"waitTime":{"$ref":"#/components/schemas/Step/properties/waitTime"}}},"SenderList":{"type":"object","properties":{"flowId":{"type":"string"},"senders":{"type":"array","items":{"$ref":"#/components/schemas/Sender"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Sender":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"replyTo":{"type":"string"},"bcc":{"type":"string"},"status":{"type":"string","enum":["enabled","disabled"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"dailySendLimit":{"type":"integer"},"warmingStatus":{"type":"string","enum":["build","maintain"]},"emailSignature":{"type":"object","properties":{"enabled":{"type":"boolean"},"content":{"type":"string"}}}}},"SenderCreate":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"replyTo":{"type":"string"},"bcc":{"type":"string"},"status":{"type":"string","enum":["enabled","disabled"]},"dailySendLimit":{"type":"integer"},"warmingStatus":{"type":"string","enum":["build","maintain"]},"emailSignature":{"type":"object","properties":{"enabled":{"type":"boolean"},"content":{"type":"string"}}}}},"ContactList":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Contact":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"status":{"type":"string","enum":["active","paused","completed","unsubscribed"]},"currentStep":{"type":"integer"},"addedAt":{"type":"string","format":"date-time"},"lastUpdated":{"type":"string","format":"date-time"}}},"ContactCreate":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"company":{"type":"string"},"status":{"type":"string","enum":["active","paused"]}}},"Pagination":{"type":"object","properties":{"totalCount":{"type":"integer"},"page":{"type":"integer"},"perPage":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}