{"openapi":"3.1.0","info":{"title":"Famulor API","summary":"REST API for assistants, calls, leads, and omnichannel customer communication workflows.","description":"Use the Famulor API to manage AI assistants, handle calls and conversations, and automate communication processes.","version":"1.0.0","contact":{"name":"Famulor Support","email":"support@famulor.io","url":"https://www.famulor.io/support"}},"servers":[{"url":"https://app.famulor.de/api","description":"Production API"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Assistants","description":"Manage AI assistants."},{"name":"Calls","description":"Create and list calls."},{"name":"Leads","description":"Create and list leads."}],"paths":{"/assistants":{"get":{"tags":["Assistants"],"operationId":"listAssistants","summary":"List assistants","description":"Returns all assistants for the authenticated account.","responses":{"200":{"description":"Assistant list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Assistant"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Assistants"],"operationId":"createAssistant","summary":"Create assistant","description":"Creates a new AI assistant.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAssistantRequest"}}}},"responses":{"201":{"description":"Assistant created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/calls":{"get":{"tags":["Calls"],"operationId":"listCalls","summary":"List calls","description":"Lists calls with optional search and status filters.","parameters":[{"in":"query","name":"search","required":false,"schema":{"type":"string","minLength":1,"maxLength":100},"description":"Free-text search over call fields."},{"in":"query","name":"status","required":false,"schema":{"type":"string","enum":["queued","in_progress","completed","failed"]},"description":"Filter calls by current status."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of results per page."},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"},"description":"Cursor token for pagination."}],"responses":{"200":{"description":"Call list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"nextCursor":{"type":"string","nullable":true}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Calls"],"operationId":"makeCall","summary":"Make a call","description":"Starts an outbound call with a selected assistant.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCallRequest"}}}},"responses":{"201":{"description":"Call created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/leads":{"get":{"tags":["Leads"],"operationId":"listLeads","summary":"List leads","description":"Lists leads with optional campaign and status filtering.","parameters":[{"in":"query","name":"campaignId","required":false,"schema":{"type":"string"},"description":"Filter leads by campaign id."},{"in":"query","name":"status","required":false,"schema":{"type":"string","enum":["new","contacted","qualified","lost"]},"description":"Filter leads by lifecycle status."},{"in":"query","name":"search","required":false,"schema":{"type":"string","minLength":1,"maxLength":100},"description":"Search by name, email, or phone."}],"responses":{"200":{"description":"Lead list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}}},"required":["data"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"tags":["Leads"],"operationId":"createLead","summary":"Create lead","description":"Creates a lead for sales or campaign workflows.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLeadRequest"}}}},"responses":{"201":{"description":"Lead created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key used to authenticate requests."}},"schemas":{"Assistant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"language":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name"]},"CreateAssistantRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"language":{"type":"string","example":"de-DE"}},"required":["name"]},"Call":{"type":"object","properties":{"id":{"type":"string"},"assistantId":{"type":"string"},"to":{"type":"string"},"status":{"type":"string","enum":["queued","in_progress","completed","failed"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","assistantId","status"]},"CreateCallRequest":{"type":"object","properties":{"assistantId":{"type":"string"},"to":{"type":"string","description":"Destination phone number in E.164 format."}},"required":["assistantId","to"]},"Lead":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email","nullable":true},"phone":{"type":"string","nullable":true},"status":{"type":"string","enum":["new","contacted","qualified","lost"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","status"]},"CreateLeadRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email"},"phone":{"type":"string"}},"required":["name"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"oneOf":[{"type":"object"},{"type":"array"},{"type":"string"},{"type":"null"}]}},"required":["code","message"]}},"required":["error"]}},"responses":{"BadRequest":{"description":"Invalid request payload or query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"BAD_REQUEST","message":"Validation failed for one or more fields.","details":[{"field":"name","issue":"required"}]}}}}},"Unauthorized":{"description":"Authentication failed or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"UNAUTHORIZED","message":"Missing or invalid API key."}}}}},"RateLimited":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many requests. Please retry later."}}}}},"InternalServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INTERNAL_SERVER_ERROR","message":"An unexpected error occurred."}}}}}}}}