{"openapi":"3.1.0","info":{"title":"Sophiie API","version":"1.0.0","description":"REST API for Sophiie - a B2B SaaS platform for sales pipeline management. These endpoints provide access to leads, inquiries, and other core data with bearer token authentication.","contact":{"name":"Sophiie API Support","url":"https://sophiie.ai"}},"tags":[{"name":"Agent Tasks"},{"name":"Appointments"},{"name":"Calls"},{"name":"Companies"},{"name":"FAQs"},{"name":"Inquiries"},{"name":"Leads"},{"name":"Members"},{"name":"Organization"},{"name":"Policies"},{"name":"Products"},{"name":"SMS"},{"name":"Scenarios"},{"name":"Services"},{"name":"Transfers"}],"servers":[{"url":"https://api.sophiie.ai","description":"Production server"},{"url":"https://api.dev.sophiie.ai","description":"Development server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication for API access."}},"schemas":{},"parameters":{}},"paths":{"/v1/agent-tasks/capabilities":{"get":{"summary":"Discover agent task capabilities","description":"Describes what the deployed agent runtime supports: task kinds and versions, result contracts, execution profiles and their limits, the organization's entitlement state, and the runtime version. Poll this before enabling a task kind rather than assuming a deploy has landed.","tags":["Agent Tasks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Capabilities of the deployed agent runtime","content":{"application/json":{"schema":{"type":"object","properties":{"contractVersion":{"type":"integer","description":"Version of the durable agent run contract this runtime speaks.","example":2},"runtime":{"type":"object","properties":{"version":{"type":"string","nullable":true,"description":"Published version of the deployed agent runtime. Null when the runtime is deployed unversioned."}},"required":["version"]},"entitlement":{"type":"object","properties":{"state":{"type":"string","enum":["ENABLED","DISABLED","UNKNOWN"],"description":"Whether agent tasks are enabled for this organization. UNKNOWN means the entitlement could not be determined and the answer should not be cached."}},"required":["state"]},"taskKinds":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"version":{"type":"integer"},"resultContract":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"integer"}},"required":["name","version"]}},"required":["kind","version","resultContract"]}},"resultContracts":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"integer"}},"required":["name","version"]}},"profiles":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"version":{"type":"integer"},"enabled":{"type":"boolean","description":"Whether this runtime will accept work pinned to the profile."},"confirmation":{"type":"string","description":"When the profile requires a human decision before a tool runs."},"resultContract":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"integer"}},"required":["name","version"]},"limits":{"type":"object","properties":{"maxTurns":{"type":"integer"},"maxMutations":{"type":"integer"},"maxMessages":{"type":"integer"},"monetaryCeiling":{"type":"number","nullable":true}},"required":["maxTurns","maxMutations","maxMessages","monetaryCeiling"]}},"required":["id","version","enabled","confirmation","resultContract","limits"]}},"limits":{"type":"object","properties":{"maxRequestBytes":{"type":"integer"}},"required":["maxRequestBytes"]}},"required":["contractVersion","runtime","entitlement","taskKinds","resultContracts","profiles","limits"]}}}},"401":{"description":"Unauthorized - invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Forbidden - the credential may not use this surface","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"429":{"description":"Rate limited - retry after the interval in `Retry-After`","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"503":{"description":"The agent runtime is not provisioned on this deployment stage","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}}}}},"/v1/agent-tasks":{"post":{"summary":"Start an agent task","description":"Accepts a task for execution and returns its id. The task runs asynchronously; poll `GET /v1/agent-tasks/{taskId}` for its status and result.\n\nRequires an `Idempotency-Key` header. Repeating a request with the same key and the same body returns the first request's response unchanged and starts nothing new. Reusing a key with a DIFFERENT body is refused with `IDEMPOTENCY_FINGERPRINT_CONFLICT` and leaves the first request untouched. Keys do not expire: a key replays its first response for as long as the record exists, so send a NEW key for work you want run again — including after a refusal, which a key replays just as it replays an acceptance.","tags":["Agent Tasks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"A value unique to this request, of your choosing. Send it again verbatim on every retry."},"required":true,"description":"A value unique to this request, of your choosing. Send it again verbatim on every retry.","name":"idempotency-key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"taskKind":{"type":"string","minLength":1,"maxLength":128,"description":"Kind of work to run, as advertised by `GET /v1/agent-tasks/capabilities`. A kind this build will not run for API credentials is refused rather than queued.","example":"BACKGROUND_TASK"},"taskKindVersion":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Version of that kind. Published versions are immutable, so pinning one is what makes the result contract predictable.","example":1},"objective":{"type":"string","minLength":1,"maxLength":8000,"description":"What the task should achieve, in plain language."},"description":{"type":"string","maxLength":8000,"default":"","description":"Any further detail the agent should work from. Optional; the objective alone is enough."}},"required":["taskKind","taskKindVersion","objective"],"additionalProperties":false}}}},"responses":{"202":{"description":"The task was accepted, or an identical earlier request's response is being returned again.","headers":{"Idempotency-Replayed":{"schema":{"type":"string","description":"`true` when this response is a replay of an earlier identical request rather than a task started now."},"required":false,"description":"`true` when this response is a replay of an earlier identical request rather than a task started now."}},"content":{"application/json":{"schema":{"type":"object","properties":{"taskId":{"type":"string","description":"Task id. Stable for the run."},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED","WAITING_FOR_INPUT","LIMIT_EXCEEDED","FAILED_TO_START"],"description":"The run's status at the moment it was accepted — ordinarily `PENDING`. It is the persisted status rather than a fixed literal, and it is not updated afterwards: a replayed response repeats the status the original request saw. Poll `GET /v1/agent-tasks/{taskId}` for the current one."}},"required":["taskId","status"]}}}},"400":{"description":"Invalid request, or a task kind this build cannot start","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Agent tasks are switched off for this organization, or this credential may not run the requested work","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"409":{"description":"The idempotency key is taken by a different request, or an identical one is still in flight","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"429":{"description":"Rate limited, or a usage ceiling refused the task before it started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"503":{"description":"The agent runtime is not provisioned on this deployment stage, or the organization's entitlement or usage ceiling could not be determined","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}}}},"get":{"summary":"List agent tasks","description":"Tasks this credential created, newest first. Broader visibility across an organization's tasks is a separate grant this deployment does not issue. Send `If-None-Match` with the previous `ETag` when polling.","tags":["Agent Tasks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Rows per page. Defaults to 25, maximum 100.","example":25},"required":false,"description":"Rows per page. Defaults to 25, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Opaque continuation token from a previous response's `nextCursor`. Do not construct one."},"required":false,"description":"Opaque continuation token from a previous response's `nextCursor`. Do not construct one.","name":"cursor","in":"query"},{"schema":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED","WAITING_FOR_INPUT","LIMIT_EXCEEDED","FAILED_TO_START"],"description":"Return only tasks in this status."},"required":false,"description":"Return only tasks in this status.","name":"status","in":"query"}],"responses":{"200":{"description":"A page of tasks","headers":{"ETag":{"schema":{"type":"string","description":"Send back as `If-None-Match` on the next poll."},"required":true,"description":"Send back as `If-None-Match` on the next poll."}},"content":{"application/json":{"schema":{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Task id. Stable for the run."},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED","WAITING_FOR_INPUT","LIMIT_EXCEEDED","FAILED_TO_START"],"description":"The run's persisted status. `WAITING_FOR_INPUT` means a human decision is outstanding; `LIMIT_EXCEEDED` and `FAILED_TO_START` are terminal and distinct from `FAILED`."},"objective":{"type":"string","description":"The objective the task was created with."},"taskKind":{"type":"string","nullable":true},"taskKindVersion":{"type":"integer","nullable":true},"attemptNumber":{"type":"integer","description":"Which attempt of this work the row represents. A retried run is a new task with the same owner and a higher attempt number."},"createdAt":{"type":"string"},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true}},"required":["id","status","objective","taskKind","taskKindVersion","attemptNumber","createdAt","startedAt","completedAt"]}},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` for the next page. Null on the last page."}},"required":["tasks","nextCursor"]}}}},"304":{"description":"The representation matches the `If-None-Match` value supplied, so no body is returned."},"400":{"description":"Invalid query parameters or continuation cursor","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Forbidden - the credential may not use this surface","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"429":{"description":"Rate limited - retry after the interval in `Retry-After`","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}}}}},"/v1/agent-tasks/{taskId}/respond":{"post":{"summary":"Answer a request an agent task is waiting on","description":"Answers one of the requests reported by `pendingRequests` on `GET /v1/agent-tasks/{taskId}`: reject a confirmation, or answer an information request. The run resumes from the answer.\n\nA 200 means the answer is both recorded and delivered to the runtime. Repeating the identical answer is safe and returns 200 again; a DIFFERENT answer to a request that already has one is refused with `DECISION_CONFLICT` rather than overwriting it.\n\nApproving a confirmation is not available here — it requires a member-authenticated surface.","tags":["Agent Tasks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Task the request belongs to."},"required":true,"description":"Task the request belongs to.","name":"taskId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["confirmation"]},"requestId":{"type":"string","minLength":1,"description":"The request being answered, as reported by `GET /v1/agent-tasks/{taskId}`."},"requestRevision":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The `requestRevision` that read reported. Answering without it is refused, and answering with a stale one is refused rather than applied — the request may have changed since you read it."},"approved":{"type":"boolean","enum":[false],"description":"Only `false`. Approving a gated action is a member-authenticated act and is not available to an API credential; rejecting is."},"feedback":{"type":"string","description":"Why the action was rejected. The agent reads this and carries on, so it is worth writing for."}},"required":["kind","requestId","requestRevision","approved"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["information"]},"requestId":{"type":"string","minLength":1,"description":"The request being answered, as reported by `GET /v1/agent-tasks/{taskId}`."},"requestRevision":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"The `requestRevision` that read reported. Answering without it is refused, and answering with a stale one is refused rather than applied — the request may have changed since you read it."},"response":{"type":"string","description":"The answer to the question the run asked."}},"required":["kind","requestId","requestRevision","response"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"The answer was recorded and delivered to the runtime","content":{"application/json":{"schema":{"type":"object","properties":{"requestId":{"type":"string","description":"The request that was answered."},"requestRevision":{"type":"integer","description":"The request's revision after the answer was recorded."}},"required":["requestId","requestRevision"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Forbidden - the credential may not answer this request","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"404":{"description":"No such task is visible to this credential, or the request is not one of that task's. Returned alike for a request that does not exist and one belonging to another credential's task.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"409":{"description":"The request cannot take this answer in its current state: the revision is stale, it already has a different answer, its deadline passed, or another responder is delivering one","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"413":{"description":"The answer exceeds the runtime's 204800-byte callback budget","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"429":{"description":"Rate limited - retry after the interval in `Retry-After`","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"502":{"description":"The runtime would not accept the answer","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"503":{"description":"The agent runtime is not provisioned on this deployment stage","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}}}}},"/v1/agent-tasks/{taskId}/cancel":{"post":{"summary":"Cancel an agent task","description":"Stops a task that has not finished. Cancelling a task that is already cancelled succeeds and does nothing, so a retry after a network failure is safe; cancelling one that has already finished is refused with `TASK_NOT_CANCELLABLE`.\n\nThe response reports the task's status and, separately, what happened to the running execution. An `execution` of `UNKNOWN` means the task is cancelled but the runtime did not confirm the execution stopped — retry to try the stop again.\n\nAvailable regardless of whether the organization is currently entitled to start new tasks: a plan change must never leave a running task unstoppable.","tags":["Agent Tasks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Task to cancel."},"required":true,"description":"Task to cancel.","name":"taskId","in":"path"}],"responses":{"200":{"description":"The task is cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED","WAITING_FOR_INPUT","LIMIT_EXCEEDED","FAILED_TO_START"],"description":"The task's persisted status after the cancel."},"execution":{"type":"string","enum":["STOPPED","NOT_RUNNING","UNKNOWN"],"description":"What happened to the running execution, separately from the task's status. `STOPPED` — the runtime confirmed it is stopped. `NOT_RUNNING` — there was no execution to stop. `UNKNOWN` — the task is cancelled, but the runtime could not confirm the execution stopped. It may still perform side effects until it is swept. Retrying the cancel retries the stop."}},"required":["status","execution"]}}}},"401":{"description":"Unauthorized - invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Forbidden - the credential may not use this surface","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"404":{"description":"No such task is visible to this credential. Returned for a task that does not exist and for one belonging to another credential alike.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"409":{"description":"The task has already finished, or a human decision on it settled while the cancel was arbitrating","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"429":{"description":"Rate limited - retry after the interval in `Retry-After`","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"503":{"description":"The agent runtime is not provisioned on this deployment stage","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}}}}},"/v1/agent-tasks/{taskId}":{"get":{"summary":"Get an agent task","description":"One task in full: its status, its typed result, the human decisions it is still waiting on, and any side effect whose outcome could not be confirmed. What it changed is a separate endpoint.","tags":["Agent Tasks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Task id, as returned by the list endpoint."},"required":true,"description":"Task id, as returned by the list endpoint.","name":"taskId","in":"path"}],"responses":{"200":{"description":"The task","headers":{"ETag":{"schema":{"type":"string","description":"Send back as `If-None-Match` on the next poll."},"required":true,"description":"Send back as `If-None-Match` on the next poll."}},"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Task id. Stable for the run."},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED","CANCELLED","WAITING_FOR_INPUT","LIMIT_EXCEEDED","FAILED_TO_START"],"description":"The run's persisted status. `WAITING_FOR_INPUT` means a human decision is outstanding; `LIMIT_EXCEEDED` and `FAILED_TO_START` are terminal and distinct from `FAILED`."},"objective":{"type":"string","description":"The objective the task was created with."},"taskKind":{"type":"string","nullable":true},"taskKindVersion":{"type":"integer","nullable":true},"attemptNumber":{"type":"integer","description":"Which attempt of this work the row represents. A retried run is a new task with the same owner and a higher attempt number."},"createdAt":{"type":"string"},"startedAt":{"type":"string","nullable":true},"completedAt":{"type":"string","nullable":true},"description":{"type":"string"},"result":{"type":"object","properties":{"contract":{"type":"object","nullable":true,"properties":{"name":{"type":"string"},"version":{"type":"integer"}},"required":["name","version"]},"payload":{"nullable":true,"description":"The typed result, shaped by `contract`. Null until the run settles with one."},"text":{"type":"string","nullable":true}},"required":["contract","text"],"description":"Present on every task. Whether the run settled is `status`, not the presence of a payload."},"failure":{"type":"string","nullable":true,"description":"Why the run ended badly. Null unless it did."},"pendingRequests":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"requestId":{"type":"string","nullable":true,"description":"The address the respond endpoint accepts. Null on rows minted before public request ids existed — those cannot be answered through this API."},"kind":{"type":"string","enum":["confirmation","information"]},"requestRevision":{"type":"integer","description":"Echo this when responding. A stale value is refused rather than applied to a request that changed underneath you."},"requiresFreshApproval":{"type":"boolean","description":"Approving this needs an explicit fresh-approval acknowledgement, which only a member-authenticated surface can give. Reported `true` when the check could not be completed."},"expiresAt":{"type":"string","nullable":true,"description":"After this the request can no longer be answered. Null means no deadline."}},"required":["requestId","kind","requestRevision","requiresFreshApproval","expiresAt"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"],"description":"Human decisions this run is still waiting on AND that can still be answered. Requests on a run that already ended, and requests past their deadline, are not listed — they cannot receive an answer."},"unresolvedEffects":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"toolName":{"type":"string"},"outcome":{"type":"string","enum":["IN_FLIGHT","UNKNOWN"],"description":"`IN_FLIGHT` — claimed and still being worked. `UNKNOWN` — the provider's answer was lost, so whether it took effect cannot be determined from here."},"claimedAt":{"type":"string"}},"required":["toolName","outcome","claimedAt"]}},"hasMore":{"type":"boolean"}},"required":["items","hasMore"],"description":"Side effects this run claimed whose outcome is not confirmed. While the run is going these are ordinarily in flight; an entry on a settled run means the effect may or may not have happened."}},"required":["id","status","objective","taskKind","taskKindVersion","attemptNumber","createdAt","startedAt","completedAt","description","result","failure","pendingRequests","unresolvedEffects"]}}}},"304":{"description":"The representation matches the `If-None-Match` value supplied, so no body is returned."},"400":{"description":"Invalid query parameters or continuation cursor","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Forbidden - the credential may not use this surface","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"404":{"description":"No such task is visible to this credential. Returned for a task that does not exist and for one belonging to another credential alike.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"429":{"description":"Rate limited - retry after the interval in `Retry-After`","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}}}}},"/v1/agent-tasks/{taskId}/artifacts":{"get":{"summary":"List what an agent task changed","description":"A page of artifact summaries: which record each tool call touched, how, and whether that individual change succeeded. The recorded before and after states are not served here — they sit behind a separate authorization.","tags":["Agent Tasks"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Task id, as returned by the list endpoint."},"required":true,"description":"Task id, as returned by the list endpoint.","name":"taskId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Rows per page. Defaults to 25, maximum 100.","example":25},"required":false,"description":"Rows per page. Defaults to 25, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"description":"Opaque continuation token from a previous response's `nextCursor`. Do not construct one."},"required":false,"description":"Opaque continuation token from a previous response's `nextCursor`. Do not construct one.","name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of artifact summaries","headers":{"ETag":{"schema":{"type":"string","description":"Send back as `If-None-Match` on the next poll."},"required":true,"description":"Send back as `If-None-Match` on the next poll."}},"content":{"application/json":{"schema":{"type":"object","properties":{"artifacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"sequenceNumber":{"type":"integer"},"entityType":{"type":"string"},"entityId":{"type":"string"},"entityDisplayName":{"type":"string","nullable":true},"operation":{"type":"string","enum":["create","update","delete"]},"toolName":{"type":"string"},"success":{"type":"boolean","description":"Whether this individual change succeeded. A failed artifact is kept, not dropped — a run can finish having failed part of its work."},"recordedAt":{"type":"string"}},"required":["id","sequenceNumber","entityType","entityId","entityDisplayName","operation","toolName","success","recordedAt"]}},"nextCursor":{"type":"string","nullable":true}},"required":["artifacts","nextCursor"]}}}},"304":{"description":"The representation matches the `If-None-Match` value supplied, so no body is returned."},"400":{"description":"Invalid query parameters or continuation cursor","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Forbidden - the credential may not use this surface","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"404":{"description":"No such task is visible to this credential. Returned for a task that does not exist and for one belonging to another credential alike.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"429":{"description":"Rate limited - retry after the interval in `Retry-After`","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"example":false},"message":{"type":"string","description":"Human-readable error message"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code"},"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","RATE_LIMITED","VALIDATION_FAILED","NOT_FOUND","WORKFLOW_UNAVAILABLE","FEATURE_DISABLED","ENTITLEMENT_UNAVAILABLE","QUOTA_UNAVAILABLE","TASK_KIND_UNSUPPORTED","IDEMPOTENCY_FINGERPRINT_CONFLICT","IDEMPOTENCY_REQUEST_IN_PROGRESS","QUOTA_EXCEEDED","REVISION_STALE","DECISION_CONFLICT","DELIVERY_IN_PROGRESS","REQUEST_EXPIRED","PAYLOAD_TOO_LARGE","UPSTREAM_CALLBACK_FAILED","TASK_NOT_CANCELLABLE","INTERNAL_ERROR"],"description":"Stable machine-readable error code. Branch on this, not on the message."},"message":{"type":"string","description":"Human-readable error message"},"lost":{"type":"boolean","enum":[true],"description":"The decision was persisted but callback delivery was lost."}},"required":["status","code","message"]}},"required":["success","message","error"]}}}}}}},"/v1/appointments":{"get":{"summary":"List Appointments","description":"Retrieve a paginated list of appointments (also referred to as Jobs). Optionally filter by lead ID. Returns appointment data including scheduling details, status, and associated lead information. Results are filtered by the organization associated with the API key.","tags":["Appointments"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter appointments by lead ID","example":"ld_abc123"},"required":false,"description":"Filter appointments by lead ID","name":"leadId","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated appointment data","content":{"application/json":{"schema":{"type":"object","properties":{"appointments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the appointment","example":"apt_abc123"},"serialId":{"type":"number","description":"Sequential ID within the organization","example":42},"title":{"type":"string","description":"Title of the appointment","example":"Installation Consultation"},"description":{"type":"string","nullable":true,"description":"Description of the appointment","example":"Initial consultation for kitchen renovation"},"start":{"type":"string","description":"Start date and time (ISO 8601)","example":"2023-12-01T10:00:00.000Z"},"end":{"type":"string","description":"End date and time (ISO 8601)","example":"2023-12-01T11:00:00.000Z"},"status":{"type":"string","description":"Current status of the appointment","example":"PENDING"},"leadId":{"type":"string","description":"Associated lead ID","example":"ld_abc123"},"attendees":{"type":"array","items":{"type":"string"},"description":"Array of attendee email addresses","example":["john.doe@example.com"]},"tradeService":{"type":"object","nullable":true,"properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"],"description":"Associated service information","example":{"id":1,"name":"Plumbing"}},"notes":{"type":"string","nullable":true,"description":"Internal notes about the appointment","example":"Customer prefers morning appointments"},"customerNotes":{"type":"string","nullable":true,"description":"Notes from the customer","example":"Please call before arriving"},"isRescheduled":{"type":"boolean","description":"Whether this appointment has been rescheduled","example":false},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","serialId","title","description","start","end","status","leadId","attendees","tradeService","notes","customerNotes","isRescheduled","createdAt"]},"description":"Array of appointments (also referred to as Jobs in some contexts)"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of appointments","example":28}},"required":["appointments","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/calls":{"post":{"summary":"Send Call","description":"Initiate a call to a phone number. The call will be made using the organization's virtual assistant associated with the API key.","tags":["Calls"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Name of the person to call","example":"John Doe"},"phoneNumber":{"type":"string","description":"Phone number of the lead","example":"+1234567890"},"mode":{"type":"string","enum":["normal","transfer_only"],"default":"normal","description":"Call mode. 'normal' for standard calls. When set to 'transfer_only', the agent will exclusively follow the provided custom instructions and only use the transfer feature from the Sophiie dashboard—no other organization data or context will be added or accessed.","example":"normal"},"custom_instructions":{"type":"string","description":"Custom instructions for the agent. Required when mode is 'transfer_only'. When in 'transfer_only' mode, the agent will ignore all other organization data and rules, using only these instructions and the transfer functionality.","example":"You are a transfer agent. Your only job is to greet the customer and transfer them to the sales team."}},"required":["name","phoneNumber"]}}}},"responses":{"200":{"description":"Call initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Call initiated successfully"}},"required":["message"]}}}},"400":{"description":"Bad request - Invalid input or call delivery failure","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"No virtual assistant phone found for organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/faqs":{"get":{"summary":"List FAQs","description":"Retrieve a paginated list of faqs. Returns FAQ data including question, answer. Results are filtered by the organization associated with the API key.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated FAQ data","content":{"application/json":{"schema":{"type":"object","properties":{"faqs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the FAQ","example":123},"question":{"type":"string","description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["id","question","answer","isActive"]},"description":"Array of FAQs"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of FAQs","example":250}},"required":["faqs","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create FAQ","description":"Create a new FAQ entry. The FAQ will be associated with the organization of the API key.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":255,"description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","minLength":1,"description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["question","answer"]}}}},"responses":{"200":{"description":"FAQ created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"faq":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the FAQ","example":123},"question":{"type":"string","description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["id","question","answer","isActive"]}},"required":["faq"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/faqs/{faqId}":{"put":{"summary":"Update FAQ","description":"Update an existing FAQ entry. Only FAQs belonging to the organization associated with the API key can be updated.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the FAQ","example":1},"required":false,"description":"The unique identifier of the FAQ","name":"faqId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","minLength":1,"maxLength":255,"description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","minLength":1,"description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}}}}}},"responses":{"200":{"description":"FAQ updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"faq":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the FAQ","example":123},"question":{"type":"string","description":"Question of the FAQ","example":"What is the question of the FAQ?"},"answer":{"type":"string","description":"Answer of the FAQ","example":"This is the answer of the FAQ"},"isActive":{"type":"boolean","description":"Whether the FAQ is active","example":true}},"required":["id","question","answer","isActive"]}},"required":["faq"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"FAQ not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete FAQ","description":"Delete an existing FAQ entry. Only FAQs belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["FAQs"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the FAQ","example":1},"required":false,"description":"The unique identifier of the FAQ","name":"faqId","in":"path"}],"responses":{"200":{"description":"FAQ deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"FAQ deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"FAQ not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/inquiries":{"get":{"summary":"List Inquiries","description":"Retrieve a paginated list of inquiries. Supports filtering by lead ID. Results are filtered by the organization associated with the API key.","tags":["Inquiries"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"},{"schema":{"type":"string","description":"Filter inquiries by lead ID","example":"ld_abc123"},"required":false,"description":"Filter inquiries by lead ID","name":"leadId","in":"query"},{"schema":{"type":"string","enum":["CALL","EMAIL","CHATBOT","SMS","WEBFORM"],"description":"Filter inquiries by source type","example":"CALL"},"required":false,"description":"Filter inquiries by source type","name":"source","in":"query"},{"schema":{"type":"string","enum":["external","lead","both"],"description":"Expand additional data: 'external' for externalInquiryId, 'lead' for lead info, 'both' for both","example":"both"},"required":false,"description":"Expand additional data: 'external' for externalInquiryId, 'lead' for lead info, 'both' for both","name":"expand","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter inquiries by archived state: 'true' returns only archived, 'false' returns only unarchived. Omit to return both.","example":"false"},"required":false,"description":"Filter inquiries by archived state: 'true' returns only archived, 'false' returns only unarchived. Omit to return both.","name":"archived","in":"query"}],"responses":{"200":{"description":"Successful response with paginated inquiry data","content":{"application/json":{"schema":{"type":"object","properties":{"inquiries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"source":{"type":"string","enum":["CALL","EMAIL","CHATBOT","SMS","WEBFORM"],"description":"Source of the inquiry","example":"CALL"},"sourceId":{"type":"string","description":"ID of the associated source record (Call, ChatbotThread, MessageThread, WebformSubmission)","example":"call_abc123"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"archived":{"type":"boolean","description":"Whether the inquiry has been archived from the inbox","example":false},"archivedAt":{"type":"string","nullable":true,"description":"Archival timestamp (ISO 8601), or null if the inquiry is not archived","example":null}},"required":["id","source","sourceId","tag","summary","isFirstInquiry","isRead","leadId","createdAt","archived","archivedAt"]},"description":"Array of inquiries"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of inquiries","example":125}},"required":["inquiries","totalPages","currentPage","totalCount"]}}}},"400":{"description":"Bad request - invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/inquiries/{inquiryId}":{"get":{"summary":"Get Inquiry","description":"Retrieve a single inquiry with populated polymorphic source data. Results are filtered by the organization associated with the API key.","tags":["Inquiries"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier for the inquiry","example":"in_abc123"},"required":true,"description":"The unique identifier for the inquiry","name":"inquiryId","in":"path"}],"responses":{"200":{"description":"Successful response with inquiry data and expanded source data","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"archived":{"type":"boolean","description":"Whether the inquiry has been archived from the inbox","example":false},"archivedAt":{"type":"string","nullable":true,"description":"Archival timestamp (ISO 8601), or null if the inquiry is not archived","example":null},"source":{"type":"string","enum":["CALL"],"description":"Source type for call inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Call ID","example":"123456"},"summary":{"type":"string","description":"Summary of the call","example":"Customer inquiry about service"},"keyPoints":{"type":"array","items":{"type":"string"},"description":"Key points from the call","example":["Interested in premium service","Needs quote"]},"recordingUrl":{"type":"string","description":"URL to the call recording","example":"https://example.com/recording.mp3"},"transcripts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"number"}]},"text":{"type":"string"},"user":{"type":"string","enum":["assistant","user","transferee"]}},"required":["id","created_at","text","user"]},"description":"Call transcripts"},"direction":{"type":"string","description":"Call direction","example":"LEAD_TO_AI"},"duration":{"type":"number","description":"Call duration in seconds","example":300},"startedAt":{"type":"string","description":"Call start time (ISO 8601)","example":"2023-01-01T10:00:00.000Z"},"endedAt":{"type":"string","description":"Call end time (ISO 8601)","example":"2023-01-01T10:05:00.000Z"},"endedBy":{"type":"string","description":"Who ended the call","example":"user"}},"required":["id","summary","keyPoints","recordingUrl","transcripts","direction","duration","startedAt","endedAt","endedBy"],"description":"Call data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","archived","archivedAt","source","data"],"description":"Inquiry with a CALL source","title":"Call Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"archived":{"type":"boolean","description":"Whether the inquiry has been archived from the inbox","example":false},"archivedAt":{"type":"string","nullable":true,"description":"Archival timestamp (ISO 8601), or null if the inquiry is not archived","example":null},"source":{"type":"string","enum":["CHATBOT"],"description":"Source type for chatbot inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Chatbot thread ID","example":"123456"},"summary":{"type":"string","description":"Summary of the chatbot conversation","example":"Customer inquiry about pricing"},"transcripts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"number"}]},"text":{"type":"string"},"user":{"type":"string","enum":["assistant","user","transferee"]}},"required":["id","created_at","text","user"]},"description":"Chatbot conversation transcripts"},"startedAt":{"type":"string","description":"Conversation start time (ISO 8601)","example":"2023-01-01T10:00:00.000Z"},"endedAt":{"type":"string","description":"Conversation end time (ISO 8601)","example":"2023-01-01T10:15:00.000Z"}},"required":["id","summary","transcripts","startedAt","endedAt"],"description":"Chatbot thread data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","archived","archivedAt","source","data"],"description":"Inquiry with a CHATBOT source","title":"Chatbot Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"archived":{"type":"boolean","description":"Whether the inquiry has been archived from the inbox","example":false},"archivedAt":{"type":"string","nullable":true,"description":"Archival timestamp (ISO 8601), or null if the inquiry is not archived","example":null},"source":{"type":"string","enum":["WEBFORM"],"description":"Source type for webform inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Webform submission ID","example":"123456"},"summary":{"type":"string","description":"Summary of the webform submission","example":"Service inquiry form"},"submissionData":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"businessName":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"address":{"type":"object","properties":{"formattedAddress":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postalCode":{"type":"string"},"country":{"type":"string","nullable":true},"lat":{"type":"string"},"lng":{"type":"string"}},"required":["formattedAddress"]},"message":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"required":["file","url"]}},"tradeServiceId":{"type":"number"},"preferredDate":{"type":"string"},"preferredTime":{"type":"string"}},"description":"Webform submission data"},"submittedAt":{"type":"string","description":"Submission timestamp (ISO 8601)","example":"2023-01-01T10:00:00.000Z"}},"required":["id","summary","submissionData","submittedAt"],"description":"Webform submission data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","archived","archivedAt","source","data"],"description":"Inquiry with a WEBFORM source","title":"Webform Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"archived":{"type":"boolean","description":"Whether the inquiry has been archived from the inbox","example":false},"archivedAt":{"type":"string","nullable":true,"description":"Archival timestamp (ISO 8601), or null if the inquiry is not archived","example":null},"source":{"type":"string","enum":["SMS"],"description":"Source type for SMS inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Message thread ID","example":"123456"},"source":{"type":"string","description":"Message source","example":"SMS"},"externalId":{"type":"string","description":"External thread ID","example":"ext_123"},"isClosed":{"type":"boolean","description":"Whether the message thread is closed","example":false},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Message ID","example":"456789"},"subject":{"type":"string","nullable":true,"description":"Message subject (for emails)","example":"Re: Service inquiry"},"content":{"type":"string","description":"Message content","example":"Hello, I'm interested in your services..."},"source":{"type":"string","description":"Message source","example":"SMS"},"direction":{"type":"string","description":"Message direction","example":"INBOUND"},"sender":{"type":"string","description":"Sender contact (email/phone)","example":"+1234567890"},"senderId":{"type":"string","description":"Sender ID","example":"ld_abc123"},"senderType":{"type":"string","description":"Sender type","example":"LEAD"},"receiver":{"type":"string","description":"Receiver contact (email/phone)","example":"+0987654321"},"receiverId":{"type":"string","description":"Receiver ID","example":"SOPHIIE_AI"},"receiverType":{"type":"string","description":"Receiver type","example":"AI_AGENT"},"externalId":{"type":"string","description":"External message ID","example":"twilio_msg_123"},"sentiment":{"type":"string","nullable":true,"description":"AI-analyzed sentiment","example":"positive"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary","example":"Customer expressing interest in premium services"},"keyPoints":{"type":"array","nullable":true,"items":{"type":"string"},"description":"AI-extracted key points","example":["Interested in premium plan","Needs pricing info"]},"attachments":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"required":["file","url"]},"description":"Message attachments"},"repliedByAI":{"type":"boolean","description":"Whether this message was replied to by AI","example":true},"createdAt":{"type":"string","description":"Message creation timestamp (ISO 8601)","example":"2023-01-01T10:00:00.000Z"}},"required":["id","subject","content","source","direction","sender","senderId","senderType","receiver","receiverId","receiverType","externalId","sentiment","summary","keyPoints","attachments","repliedByAI","createdAt"]},"description":"All messages in the thread"}},"required":["id","source","externalId","isClosed","messages"],"description":"SMS message data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","archived","archivedAt","source","data"],"description":"Inquiry with a SMS source","title":"SMS Inquiry"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"tag":{"type":"string","nullable":true,"description":"Tag associated with the inquiry","example":"urgent"},"summary":{"type":"string","description":"Summary of the inquiry","example":"Customer inquiry about new service offering"},"isFirstInquiry":{"type":"boolean","description":"Whether this is the first inquiry from the lead","example":true},"isRead":{"type":"boolean","description":"Whether the inquiry has been read","example":false},"leadId":{"type":"string","description":"ID of the associated lead","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"archived":{"type":"boolean","description":"Whether the inquiry has been archived from the inbox","example":false},"archivedAt":{"type":"string","nullable":true,"description":"Archival timestamp (ISO 8601), or null if the inquiry is not archived","example":null},"source":{"type":"string","enum":["EMAIL"],"description":"Source type for email inquiries"},"data":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Message thread ID","example":"123456"},"source":{"type":"string","description":"Message source","example":"SMS"},"externalId":{"type":"string","description":"External thread ID","example":"ext_123"},"isClosed":{"type":"boolean","description":"Whether the message thread is closed","example":false},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Message ID","example":"456789"},"subject":{"type":"string","nullable":true,"description":"Message subject (for emails)","example":"Re: Service inquiry"},"content":{"type":"string","description":"Message content","example":"Hello, I'm interested in your services..."},"source":{"type":"string","description":"Message source","example":"SMS"},"direction":{"type":"string","description":"Message direction","example":"INBOUND"},"sender":{"type":"string","description":"Sender contact (email/phone)","example":"+1234567890"},"senderId":{"type":"string","description":"Sender ID","example":"ld_abc123"},"senderType":{"type":"string","description":"Sender type","example":"LEAD"},"receiver":{"type":"string","description":"Receiver contact (email/phone)","example":"+0987654321"},"receiverId":{"type":"string","description":"Receiver ID","example":"SOPHIIE_AI"},"receiverType":{"type":"string","description":"Receiver type","example":"AI_AGENT"},"externalId":{"type":"string","description":"External message ID","example":"twilio_msg_123"},"sentiment":{"type":"string","nullable":true,"description":"AI-analyzed sentiment","example":"positive"},"summary":{"type":"string","nullable":true,"description":"AI-generated summary","example":"Customer expressing interest in premium services"},"keyPoints":{"type":"array","nullable":true,"items":{"type":"string"},"description":"AI-extracted key points","example":["Interested in premium plan","Needs pricing info"]},"attachments":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"url":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"}},"required":["file","url"]},"description":"Message attachments"},"repliedByAI":{"type":"boolean","description":"Whether this message was replied to by AI","example":true},"createdAt":{"type":"string","description":"Message creation timestamp (ISO 8601)","example":"2023-01-01T10:00:00.000Z"}},"required":["id","subject","content","source","direction","sender","senderId","senderType","receiver","receiverId","receiverType","externalId","sentiment","summary","keyPoints","attachments","repliedByAI","createdAt"]},"description":"All messages in the thread"}},"required":["id","source","externalId","isClosed","messages"],"description":"Email message data associated with the inquiry"}},"required":["id","tag","summary","isFirstInquiry","isRead","leadId","createdAt","archived","archivedAt","source","data"],"description":"Inquiry with a EMAIL source","title":"Email Inquiry"}],"description":"Inquiry with expanded polymorphic source data"}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Inquiry not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/inquiries/{inquiryId}/archive":{"patch":{"summary":"Archive Inquiry","description":"Archive or unarchive an inquiry. The inquiry must belong to the organization associated with the API key. Idempotent: repeating the current state is a no-op that returns the unchanged resource.","tags":["Inquiries"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier for the inquiry","example":"in_abc123"},"required":true,"description":"The unique identifier for the inquiry","name":"inquiryId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"archived":{"type":"boolean","description":"Whether the inquiry should be archived from the inbox (true) or restored (false)","example":true}},"required":["archived"]}}}},"responses":{"200":{"description":"Inquiry updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the inquiry","example":"in_xyz789"},"archived":{"type":"boolean","description":"Whether the inquiry is archived from the inbox","example":true},"archivedAt":{"type":"string","nullable":true,"description":"Archival timestamp (ISO 8601), or null if the inquiry is not archived","example":"2023-01-01T00:00:00.000Z"}},"required":["id","archived","archivedAt"]}}}},"400":{"description":"Bad request - invalid body","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Inquiry not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/companies/{companyId}/notes":{"get":{"summary":"List Company Notes","description":"Retrieve a paginated list of notes for a specific company. Returns note data including content, creation timestamps, and associated user information. Results are filtered by the organization associated with the API key.","tags":["Companies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the company","example":"cmp_abc123"},"required":true,"description":"The unique identifier of the company","name":"companyId","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated note data","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the note","example":123},"value":{"type":"string","description":"Content of the note","example":"Follow up with property manager about maintenance schedule"},"companyId":{"type":"string","description":"Associated company ID","example":"cmp_abc123"},"userId":{"type":"string","description":"User who created the note","example":"usr_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"Last update timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","value","companyId","userId","createdAt","updatedAt"]},"description":"Array of company notes"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of notes","example":15}},"required":["notes","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Company not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads":{"get":{"summary":"List Leads","description":"Retrieve a paginated list of leads. Returns lead data including contact information, status, and inquiry statistics. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated lead data","content":{"application/json":{"schema":{"type":"object","properties":{"leads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"read":{"type":"boolean","description":"Whether the lead has been read","example":false},"lastInquiryId":{"type":"string","nullable":true,"description":"ID of the last inquiry from this lead","example":"in_abc123"},"lastInquiryDate":{"type":"string","nullable":true,"description":"Date of the last inquiry from this lead (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"unreadEmails":{"type":"number","nullable":true,"description":"Number of unread emails","example":0},"unreadCalls":{"type":"number","nullable":true,"description":"Number of unread calls","example":1},"unreadChatbotThreads":{"type":"number","nullable":true,"description":"Number of unread chatbot threads","example":0},"unreadSMS":{"type":"number","nullable":true,"description":"Number of unread SMS messages","example":0},"unreadWebformSubmissions":{"type":"number","nullable":true,"description":"Number of unread webform submissions","example":0},"hasFlaggedInquiry":{"type":"boolean","description":"Whether the lead has any flagged inquiries","example":false}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt","read","lastInquiryId","lastInquiryDate","unreadEmails","unreadCalls","unreadChatbotThreads","unreadSMS","unreadWebformSubmissions","hasFlaggedInquiry"]},"description":"Array of leads"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of leads","example":250}},"required":["leads","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Lead","description":"Create a new lead entry. The lead will be associated with the organization of the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":2,"maxLength":255,"description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"format":"email","description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead. International E.164 preferred (e.g. +61412345678); local formats are converted using the organization's country and stored as E.164.","example":"+61412345678"},"suburb":{"type":"string","maxLength":255,"default":"","description":"Suburb/location of the lead (optional)","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","properties":{"instagram":{"type":"string","description":"Instagram URL","example":"https://www.instagram.com/john.doe"},"facebook":{"type":"string","description":"Facebook URL","example":"https://www.facebook.com/john.doe"}}}},"required":["firstName"]}}}},"responses":{"200":{"description":"Lead created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"lead":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt"]}},"required":["lead"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Conflict - Lead already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads/{leadId}":{"get":{"summary":"Get Lead Details","description":"Retrieve detailed information for a specific lead and address information. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"}],"responses":{"200":{"description":"Successful response with detailed lead data","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"read":{"type":"boolean","description":"Whether the lead has been read","example":false},"lastInquiryId":{"type":"string","nullable":true,"description":"ID of the last inquiry from this lead","example":"in_abc123"},"lastInquiryDate":{"type":"string","nullable":true,"description":"Date of the last inquiry from this lead (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"unreadEmails":{"type":"number","nullable":true,"description":"Number of unread emails","example":0},"unreadCalls":{"type":"number","nullable":true,"description":"Number of unread calls","example":1},"unreadChatbotThreads":{"type":"number","nullable":true,"description":"Number of unread chatbot threads","example":0},"unreadSMS":{"type":"number","nullable":true,"description":"Number of unread SMS messages","example":0},"unreadWebformSubmissions":{"type":"number","nullable":true,"description":"Number of unread webform submissions","example":0},"hasFlaggedInquiry":{"type":"boolean","description":"Whether the lead has any flagged inquiries","example":false},"defaultLeadAddress":{"type":"object","nullable":true,"properties":{"address":{"type":"object","nullable":true,"properties":{"line1":{"type":"string","nullable":true},"line2":{"type":"string","nullable":true},"suburb":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"postcode":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}},"required":["line1","line2","suburb","state","postcode","country"]}},"required":["address"],"description":"Default address for the lead"},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true}},"required":["name","description"]},"description":"Tags associated with the lead"},"lastInquiry":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"tag":{"type":"string","nullable":true},"summary":{"type":"string"},"isFirstInquiry":{"type":"boolean"},"source":{"type":"string"},"isRead":{"type":"boolean"}},"required":["id","tag","summary","isFirstInquiry","source","isRead"],"description":"Last inquiry from the lead"}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt","read","lastInquiryId","lastInquiryDate","unreadEmails","unreadCalls","unreadChatbotThreads","unreadSMS","unreadWebformSubmissions","hasFlaggedInquiry","defaultLeadAddress","tags","lastInquiry"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Lead","description":"Update a new lead entry. The lead will be associated with the organization of the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":2,"maxLength":255,"description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"format":"email","description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead. International E.164 preferred (e.g. +61412345678); local formats are converted using the organization's country and stored as E.164.","example":"+61412345678"},"suburb":{"type":"string","maxLength":255,"description":"Suburb/location of the lead (optional)","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","properties":{"instagram":{"type":"string","description":"Instagram URL","example":"https://www.instagram.com/john.doe"},"facebook":{"type":"string","description":"Facebook URL","example":"https://www.facebook.com/john.doe"}}}}}}}},"responses":{"200":{"description":"Lead updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"lead":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"firstName":{"type":"string","description":"First name of the lead","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the lead","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email address of the lead","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the lead","example":"+1234567890"},"suburb":{"type":"string","nullable":true,"description":"Suburb/location of the lead","example":"Downtown"},"businessName":{"type":"string","nullable":true,"description":"Business name of the lead","example":"Acme Corp"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media information","example":{}},"status":{"type":"string","description":"Current status of the lead","example":"active"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","firstName","lastName","email","phone","suburb","businessName","socials","status","createdAt"]}},"required":["lead"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Conflict - Lead already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Lead","description":"Soft delete a lead and related entities, sync deletion to external systems, and emit relevant webhooks. Only leads belonging to the organization associated with the API key can be deleted.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"}],"responses":{"200":{"description":"Lead deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Lead deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads/{leadId}/notes":{"get":{"summary":"List Lead Notes","description":"Retrieve a paginated list of notes for a specific lead. Returns note data including content, creation timestamps, and associated user information. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated note data","content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the note","example":123},"value":{"type":"string","description":"Content of the note","example":"Customer mentioned they need installation next week"},"appointmentId":{"type":"string","nullable":true,"description":"Associated appointment ID if linked to an appointment","example":"apt_abc123"},"leadId":{"type":"string","description":"Associated lead ID","example":"ld_abc123"},"userId":{"type":"string","description":"User who created the note","example":"usr_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"Last update timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","value","appointmentId","leadId","userId","createdAt","updatedAt"]},"description":"Array of notes"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of notes","example":15}},"required":["notes","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/leads/{leadId}/activities":{"get":{"summary":"List Lead Activities","description":"Retrieve a paginated list of activities for a specific lead. Returns activity data including event types, timestamps, and associated data. Results are filtered by the organization associated with the API key.","tags":["Leads"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"The unique identifier of the lead","example":"ld_abc123"},"required":true,"description":"The unique identifier of the lead","name":"leadId","in":"path"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated activity data","content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the activity","example":456},"event":{"type":"string","description":"Type of activity event","example":"LEAD_CREATED"},"data":{"type":"string","nullable":true,"description":"Additional data associated with the activity","example":"Status changed from pending to active"},"referenceId":{"type":"string","nullable":true,"description":"Reference ID to related entity (appointment, note, etc.)","example":"apt_abc123"},"userId":{"type":"string","nullable":true,"description":"User who triggered the activity (null if system-generated)","example":"usr_abc123"},"leadId":{"type":"string","description":"Associated lead ID","example":"ld_abc123"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","event","data","referenceId","userId","leadId","createdAt"]},"description":"Array of activities"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of activities","example":42}},"required":["activities","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/members":{"get":{"summary":"List Members","description":"Retrieve a paginated list of members. Results are filtered by the organization associated with the API key.","tags":["Members"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated member data","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the member","example":"usr_123"},"role":{"type":"string","enum":["OWNER","ADMIN","USER"],"description":"Role of the member","example":"OWNER"},"firstName":{"type":"string","nullable":true,"description":"First name of the member","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the member","example":"Doe"},"email":{"type":"string","nullable":true,"description":"Email of the member","example":"john.doe@example.com"},"phone":{"type":"string","nullable":true,"description":"Phone number of the member","example":"+1234567890"},"isDisabled":{"type":"boolean","description":"Whether the membership is disabled","example":false},"responsibility":{"type":"string","nullable":true,"description":"Member's responsibility in the organization","example":"Manages daily operations and customer service"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"}},"required":["id","role","firstName","lastName","email","phone","isDisabled","responsibility","createdAt"]},"description":"Array of members"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of members","example":250}},"required":["members","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization":{"get":{"summary":"Get Organization Details","description":"Retrieve detailed information about the organization associated with the API key. Returns organization settings, contact information, and configuration details.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with organization details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the organization","example":"org_abc123"},"name":{"type":"string","description":"Name of the organization","example":"Acme Plumbing Services"},"businessPhone":{"type":"string","nullable":true,"description":"Business phone number","example":"+1234567890"},"website":{"type":"string","nullable":true,"description":"Organization website URL","example":"https://acmeplumbing.com"},"socials":{"type":"object","additionalProperties":{"type":"string","nullable":true},"description":"Social media links and information","example":{"facebook":"acmeplumbing","instagram":"acme_plumbing"}},"timeZone":{"type":"string","description":"Organization timezone","example":"Australia/Sydney"},"country":{"type":"string","description":"Country code","example":"AU"},"currency":{"type":"string","description":"Currency code","example":"AUD"},"timeFormat":{"type":"number","description":"Time format preference (12 or 24)","example":12},"weekStart":{"type":"string","description":"First day of the week","example":"Monday"}},"required":["id","name","businessPhone","website","socials","timeZone","country","currency","timeFormat","weekStart"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/availability":{"get":{"summary":"Get Organization Availability","description":"Retrieve the availability schedules for the organization. Returns schedule information including available time slots, timezone, and day configurations for business hours.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with organization availability schedules","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Schedule ID","example":1},"name":{"type":"string","description":"Schedule name","example":"Business Hours"},"timeZone":{"type":"string","nullable":true,"description":"Schedule timezone (inherits from organization if null)","example":"Australia/Sydney"},"orgId":{"type":"string","description":"Organization ID","example":"org_abc123"},"availability":{"type":"array","items":{"type":"object","properties":{"days":{"type":"array","items":{"type":"string"},"description":"Days of the week for this availability slot","example":["Monday","Tuesday","Wednesday"]},"startTime":{"type":"string","description":"Start time in HH:mm format","example":"09:00"},"endTime":{"type":"string","description":"End time in HH:mm format","example":"17:00"}},"required":["days","startTime","endTime"]},"description":"Available time slots"}},"required":["id","name","timeZone","orgId","availability"]},"description":"Organization availability schedules"}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Organization or availability not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/members":{"get":{"summary":"List Organization Members","description":"Retrieve a paginated list of organization members. Excludes pending invitations (users without associated user accounts). Returns member information including roles, contact details, and user associations.","tags":["Organization"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated member data","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the membership","example":123},"role":{"type":"string","description":"Role of the member in the organization","example":"ADMIN"},"firstName":{"type":"string","nullable":true,"description":"First name of the member","example":"John"},"lastName":{"type":"string","nullable":true,"description":"Last name of the member","example":"Doe"},"position":{"type":"string","nullable":true,"description":"Position/title of the member","example":"Operations Manager"},"avatarImg":{"type":"string","nullable":true,"description":"Avatar image URL or asset key","example":"https://example.com/avatar.jpg"},"isDisabled":{"type":"boolean","description":"Whether the membership is disabled","example":false},"responsibility":{"type":"string","nullable":true,"description":"Member's responsibility in the organization","example":"Manages daily operations and customer service"},"user":{"type":"object","nullable":true,"properties":{"email":{"type":"string"}},"required":["email"],"description":"Associated user information","example":{"email":"john.doe@acme.com"}}},"required":["id","role","firstName","lastName","position","avatarImg","isDisabled","responsibility","user"]},"description":"Array of organization members (excludes pending invitations)"},"totalPages":{"type":"number","description":"Total number of pages available","example":2},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of members","example":8}},"required":["members","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/services":{"get":{"summary":"List Organization Services","description":"Retrieve all services for the organization, grouped by trade categories. Returns service information including names, descriptions, durations, and follow-up questions organized by their respective categories.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with services grouped by categories","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the category","example":1},"name":{"type":"string","description":"Name of the category","example":"Kitchen Services"},"type":{"type":"string","description":"Type of the category","example":"SERVICE"},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the service","example":123},"name":{"type":"string","description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","description":"Description of the service","example":"Complete kitchen renovation and installation service"},"duration":{"type":"number","nullable":true,"description":"Service duration in minutes","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service","example":[]},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":1},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"isActive":{"type":"boolean","description":"Whether the service is active","example":true}},"required":["id","name","description","duration","durationUnit","followUpQuestions","tradeCategoryId","createdAt","isActive"]},"description":"Services in this category"}},"required":["id","name","type","services"]},"description":"Array of service categories with their associated services"},"totalCategories":{"type":"number","description":"Total number of categories","example":5},"totalServices":{"type":"number","description":"Total number of services across all categories","example":23}},"required":["categories","totalCategories","totalServices"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/organization/products":{"get":{"summary":"List Organization Products","description":"Retrieve all products for the organization, grouped by trade categories. Returns product information including names, descriptions, and pricing organized by their respective categories.","tags":["Organization"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response with products grouped by categories","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the category","example":2},"name":{"type":"string","description":"Name of the category","example":"Kitchen Materials"},"type":{"type":"string","description":"Type of the category","example":"PRODUCT"},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the product","example":456},"name":{"type":"string","description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","description":"Description of the product","example":"High-quality granite countertop with polished finish"},"price":{"type":"number","description":"Product price","example":299.99},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":2},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"isActive":{"type":"boolean","description":"Whether the product is active","example":true}},"required":["id","name","description","price","tradeCategoryId","createdAt","isActive"]},"description":"Products in this category"}},"required":["id","name","type","products"]},"description":"Array of product categories with their associated products"},"totalCategories":{"type":"number","description":"Total number of categories","example":3},"totalProducts":{"type":"number","description":"Total number of products across all categories","example":47}},"required":["categories","totalCategories","totalProducts"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/policies":{"get":{"summary":"List Policies","description":"Retrieve a paginated list of policies. Returns policy data including title, content, and summary. Results are filtered by the organization associated with the API key.","tags":["Policies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated policy data","content":{"application/json":{"schema":{"type":"object","properties":{"policies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the policy","example":123},"title":{"type":"string","description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["id","title","content","isActive"]},"description":"Array of policies"},"totalPages":{"type":"number","description":"Total number of pages available","example":5},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of policies","example":250}},"required":["policies","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Policy","description":"Create a new policy entry. The policy will be associated with the organization of the API key.","tags":["Policies"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":255,"description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","minLength":2,"description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["title","content"]}}}},"responses":{"200":{"description":"Policy created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the policy","example":123},"title":{"type":"string","description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["id","title","content","isActive"]}},"required":["policy"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/policies/{policyId}":{"put":{"summary":"Update Policy","description":"Update an existing policy entry. Only policies belonging to the organization associated with the API key can be updated.","tags":["Policies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the policy","example":1},"required":false,"description":"The unique identifier of the policy","name":"policyId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":2,"maxLength":255,"description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","minLength":2,"description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}}}}}},"responses":{"200":{"description":"Policy updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"policy":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the policy","example":123},"title":{"type":"string","description":"Title of the policy","example":"Privacy Policy"},"content":{"type":"string","description":"Content of the policy","example":"This is the content of the policy"},"isActive":{"type":"boolean","description":"Whether the policy is active","example":true}},"required":["id","title","content","isActive"]}},"required":["policy"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Policy","description":"Delete an existing policy entry. Only policies belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["Policies"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the policy","example":1},"required":false,"description":"The unique identifier of the policy","name":"policyId","in":"path"}],"responses":{"200":{"description":"Policy deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Policy deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/products/{productId}":{"get":{"summary":"Get Product","description":"Retrieve a single trade product by ID. Only products belonging to the organization associated with the API key can be retrieved.","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the product","example":456},"required":false,"description":"The unique identifier of the product","name":"productId","in":"path"}],"responses":{"200":{"description":"Successful response with product data","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the product","example":456},"name":{"type":"string","description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","description":"Description of the product","example":"High-quality granite countertop with polished finish"},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":2},"pricingType":{"type":"string","nullable":true,"enum":["NONE","FIXED","RANGE",null],"description":"The pricing type for this product. null means NONE.","example":"FIXED"},"price":{"type":"number","description":"Product price (for FIXED this is the price; for RANGE this is the minimum)","example":299.99},"maxPrice":{"type":"number","description":"Maximum price when pricingType is RANGE, otherwise 0","example":499.99},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"description":"FAQ question text","example":"What materials do you use?"},"answer":{"type":"string","minLength":3,"description":"FAQ answer text","example":"We use high-quality granite sourced locally."}},"required":["question","answer"]},"description":"List of FAQs for this product"},"isActive":{"type":"boolean","description":"Whether the product is active","example":true},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the product was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","tradeCategoryId","pricingType","price","maxPrice","isDisclosePrice","faqs","isActive","createdAt","updatedAt"]}},"required":["product"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Product","description":"Update an existing trade product. Only products belonging to the organization associated with the API key can be updated.","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the product","example":456},"required":false,"description":"The unique identifier of the product","name":"productId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":100,"description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","minLength":3,"description":"Description of the product","example":"High-quality granite countertop with polished finish"},"response":{"type":"string","maxLength":1000,"description":"AI response template for the product","example":"Our premium granite countertops are..."},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"description":"FAQ question text","example":"What materials do you use?"},"answer":{"type":"string","minLength":3,"description":"FAQ answer text","example":"We use high-quality granite sourced locally."}},"required":["question","answer"]},"description":"List of FAQs for this product"},"tradeCategoryId":{"type":"number","nullable":true,"description":"Associated trade category ID","example":2},"pricing":{"oneOf":[{"type":"object","properties":{"pricingType":{"type":"string","enum":["NONE"]}},"required":["pricingType"],"title":"NonePricing"},{"type":"object","properties":{"pricingType":{"type":"string","enum":["FIXED"]},"price":{"type":"number","nullable":true,"minimum":0,"description":"Fixed price","example":299.99},"isDisclosePrice":{"type":"boolean","default":true,"description":"Whether Sophiie can disclose the price to the customer","example":true}},"required":["pricingType","price"],"title":"FixedPricing"},{"type":"object","properties":{"pricingType":{"type":"string","enum":["RANGE"]},"price":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price for the range","example":199.99},"maxPrice":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price for the range","example":499.99},"isDisclosePrice":{"type":"boolean","default":true,"description":"Whether Sophiie can disclose the price to the customer","example":true}},"required":["pricingType","price","maxPrice"],"title":"RangePricing"}],"description":"Pricing configuration for the product"}},"description":"Request body for updating a product"}}}},"responses":{"200":{"description":"Product updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the product","example":456},"name":{"type":"string","description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","description":"Description of the product","example":"High-quality granite countertop with polished finish"},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":2},"pricingType":{"type":"string","nullable":true,"enum":["NONE","FIXED","RANGE",null],"description":"The pricing type for this product. null means NONE.","example":"FIXED"},"price":{"type":"number","description":"Product price (for FIXED this is the price; for RANGE this is the minimum)","example":299.99},"maxPrice":{"type":"number","description":"Maximum price when pricingType is RANGE, otherwise 0","example":499.99},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"description":"FAQ question text","example":"What materials do you use?"},"answer":{"type":"string","minLength":3,"description":"FAQ answer text","example":"We use high-quality granite sourced locally."}},"required":["question","answer"]},"description":"List of FAQs for this product"},"isActive":{"type":"boolean","description":"Whether the product is active","example":true},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the product was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","tradeCategoryId","pricingType","price","maxPrice","isDisclosePrice","faqs","isActive","createdAt","updatedAt"]}},"required":["product"]}}}},"400":{"description":"Bad request - trade category not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"A product with the same name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Product","description":"Soft-delete an existing trade product. Only products belonging to the organization associated with the API key can be deleted.","tags":["Products"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the product","example":456},"required":false,"description":"The unique identifier of the product","name":"productId","in":"path"}],"responses":{"200":{"description":"Product deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Product deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/products":{"post":{"summary":"Create Product","description":"Create a new trade product. The product will be associated with the organization of the API key.","tags":["Products"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":100,"description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","minLength":3,"description":"Description of the product","example":"High-quality granite countertop with polished finish"},"response":{"type":"string","maxLength":1000,"description":"AI response template for the product","example":"Our premium granite countertops are..."},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"description":"FAQ question text","example":"What materials do you use?"},"answer":{"type":"string","minLength":3,"description":"FAQ answer text","example":"We use high-quality granite sourced locally."}},"required":["question","answer"]},"description":"List of FAQs for this product"},"tradeCategoryId":{"type":"number","nullable":true,"description":"Associated trade category ID","example":2}},"required":["name","description","response","faqs","tradeCategoryId"]},{"oneOf":[{"type":"object","properties":{"pricingType":{"type":"string","enum":["NONE"]}},"required":["pricingType"],"title":"NonePricing"},{"type":"object","properties":{"pricingType":{"type":"string","enum":["FIXED"]},"price":{"type":"number","nullable":true,"minimum":0,"description":"Fixed price","example":299.99},"isDisclosePrice":{"type":"boolean","default":true,"description":"Whether Sophiie can disclose the price to the customer","example":true}},"required":["pricingType","price"],"title":"FixedPricing"},{"type":"object","properties":{"pricingType":{"type":"string","enum":["RANGE"]},"price":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price for the range","example":199.99},"maxPrice":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price for the range","example":499.99},"isDisclosePrice":{"type":"boolean","default":true,"description":"Whether Sophiie can disclose the price to the customer","example":true}},"required":["pricingType","price","maxPrice"],"title":"RangePricing"}],"description":"Pricing configuration. Shape depends on `pricingType`: NONE (no pricing), FIXED (single price), RANGE (min/max price)."}],"description":"Request body for creating a product"}}}},"responses":{"200":{"description":"Product created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the product","example":456},"name":{"type":"string","description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","description":"Description of the product","example":"High-quality granite countertop with polished finish"},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":2},"pricingType":{"type":"string","nullable":true,"enum":["NONE","FIXED","RANGE",null],"description":"The pricing type for this product. null means NONE.","example":"FIXED"},"price":{"type":"number","description":"Product price (for FIXED this is the price; for RANGE this is the minimum)","example":299.99},"maxPrice":{"type":"number","description":"Maximum price when pricingType is RANGE, otherwise 0","example":499.99},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"description":"FAQ question text","example":"What materials do you use?"},"answer":{"type":"string","minLength":3,"description":"FAQ answer text","example":"We use high-quality granite sourced locally."}},"required":["question","answer"]},"description":"List of FAQs for this product"},"isActive":{"type":"boolean","description":"Whether the product is active","example":true},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the product was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","tradeCategoryId","pricingType","price","maxPrice","isDisclosePrice","faqs","isActive","createdAt","updatedAt"]}},"required":["product"]}}}},"400":{"description":"Bad request - trade category not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Conflict - a product with the same name already exists, or product quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/products/batch":{"patch":{"summary":"Batch Update Products","description":"Update up to 100 trade products in one request. Items are processed sequentially and failures are reported per item without rolling back successful updates.","tags":["Products"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the product to update","example":456},"name":{"type":"string","minLength":3,"maxLength":100,"description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","minLength":3,"description":"Description of the product","example":"High-quality granite countertop with polished finish"},"response":{"type":"string","maxLength":1000,"description":"AI response template for the product","example":"Our premium granite countertops are..."},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"description":"FAQ question text","example":"What materials do you use?"},"answer":{"type":"string","minLength":3,"description":"FAQ answer text","example":"We use high-quality granite sourced locally."}},"required":["question","answer"]},"description":"List of FAQs for this product"},"tradeCategoryId":{"type":"number","nullable":true,"description":"Associated trade category ID","example":2},"pricing":{"oneOf":[{"type":"object","properties":{"pricingType":{"type":"string","enum":["NONE"]}},"required":["pricingType"],"title":"NonePricing"},{"type":"object","properties":{"pricingType":{"type":"string","enum":["FIXED"]},"price":{"type":"number","nullable":true,"minimum":0,"description":"Fixed price","example":299.99},"isDisclosePrice":{"type":"boolean","default":true,"description":"Whether Sophiie can disclose the price to the customer","example":true}},"required":["pricingType","price"],"title":"FixedPricing"},{"type":"object","properties":{"pricingType":{"type":"string","enum":["RANGE"]},"price":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price for the range","example":199.99},"maxPrice":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price for the range","example":499.99},"isDisclosePrice":{"type":"boolean","default":true,"description":"Whether Sophiie can disclose the price to the customer","example":true}},"required":["pricingType","price","maxPrice"],"title":"RangePricing"}],"description":"Pricing configuration for the product"}},"required":["id"],"description":"One product update in the batch","example":{"id":456,"pricing":{"pricingType":"FIXED","price":12500,"isDisclosePrice":true}}},"minItems":1,"maxItems":100,"description":"Product updates to process sequentially. Maximum 100."}},"required":["updates"],"description":"Request body for updating products in a batch","example":{"updates":[{"id":456,"pricing":{"pricingType":"FIXED","price":12500,"isDisclosePrice":true}},{"id":457,"name":"Renamed product"}]}}}}},"responses":{"200":{"description":"Batch processed successfully, including partial failures","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"number","description":"Product ID from the request item","example":456},"status":{"type":"string","enum":["ok"],"description":"Per-item update status","example":"ok"},"product":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the product","example":456},"name":{"type":"string","description":"Name of the product","example":"Premium Granite Countertop"},"description":{"type":"string","description":"Description of the product","example":"High-quality granite countertop with polished finish"},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":2},"pricingType":{"type":"string","nullable":true,"enum":["NONE","FIXED","RANGE",null],"description":"The pricing type for this product. null means NONE.","example":"FIXED"},"price":{"type":"number","description":"Product price (for FIXED this is the price; for RANGE this is the minimum)","example":299.99},"maxPrice":{"type":"number","description":"Maximum price when pricingType is RANGE, otherwise 0","example":499.99},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"description":"FAQ question text","example":"What materials do you use?"},"answer":{"type":"string","minLength":3,"description":"FAQ answer text","example":"We use high-quality granite sourced locally."}},"required":["question","answer"]},"description":"List of FAQs for this product"},"isActive":{"type":"boolean","description":"Whether the product is active","example":true},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the product was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","tradeCategoryId","pricingType","price","maxPrice","isDisclosePrice","faqs","isActive","createdAt","updatedAt"]}},"required":["id","status","product"]},{"type":"object","properties":{"id":{"type":"number","description":"Product ID from the request item","example":457},"status":{"type":"string","enum":["error"],"description":"Per-item update status","example":"error"},"code":{"type":"string","enum":["NOT_FOUND","INVALID_CATEGORY","INVALID_DESTINATION","DUPLICATE_NAME","CONFLICT","ATTACHMENT_TOO_LARGE","INTERNAL_ERROR"],"description":"Machine-readable per-item error code","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable per-item error message","example":"Trade product not found"}},"required":["id","status","code","message"]}]},"description":"Per-item update results in request order"},"summary":{"type":"object","properties":{"total":{"type":"number","description":"Total number of requested updates","example":2},"succeeded":{"type":"number","description":"Number of successful updates","example":1},"failed":{"type":"number","description":"Number of failed updates","example":1}},"required":["total","succeeded","failed"]}},"required":["results","summary"],"description":"Batch product update response","example":{"results":[{"id":456,"status":"ok","product":{"id":456,"name":"Premium Granite Countertop","description":"High-quality granite countertop with polished finish","tradeCategoryId":2,"pricingType":"FIXED","price":12500,"maxPrice":0,"isDisclosePrice":true,"faqs":[],"isActive":true,"createdAt":"2023-01-01T00:00:00.000Z","updatedAt":"2023-01-20T14:00:00.000Z"}},{"id":457,"status":"error","code":"NOT_FOUND","message":"Trade product not found"}],"summary":{"total":2,"succeeded":1,"failed":1}}}}}},"400":{"description":"Bad request - malformed body or batch size exceeds 100","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Batch size exceeds maximum of 100 items"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"code":{"type":"string","enum":["BATCH_TOO_LARGE"],"description":"Machine-readable error code","example":"BATCH_TOO_LARGE"},"message":{"type":"string","description":"Error message","example":"Batch size exceeds maximum of 100 items"}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/scenarios":{"get":{"summary":"List Scenarios","description":"Retrieve a paginated list of scenarios. Returns scenario data including name, prompt, response, questions, and outcome. Results are filtered by the organization associated with the API key.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated scenario data","content":{"application/json":{"schema":{"type":"object","properties":{"scenarios":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]},"description":"Array of scenarios"},"totalPages":{"type":"number","description":"Total number of pages available","example":3},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of scenarios","example":25}},"required":["scenarios","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Scenario","description":"Create a new scenario. The scenario will be associated with the organization of the API key.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","minLength":1,"description":"The prompt / instructions for the scenario","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","minLength":1,"description":"The response template for the scenario","example":"I would be happy to help you with pricing."},"isActive":{"type":"boolean","description":"Whether the scenario is active (defaults to true)","example":true},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["transferCall"]},"transferId":{"type":"number","description":"The transfer ID linking to the transfer table","example":7},"method":{"type":"string","enum":["WARM","COLD"],"description":"Transfer method: WARM (with summary) or COLD (direct)","example":"WARM"}},"required":["type","transferId","method"],"title":"TransferCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendSMS"]},"content":{"type":"string","description":"SMS content to send","example":"Thank you for calling! Here is the information you requested."}},"required":["type","content"],"title":"SendSMSOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendEmail"]},"subject":{"type":"string","description":"Email subject line","example":"Follow-up from your call"},"content":{"type":"string","description":"Email body content (HTML supported)","example":"<p>Thank you for reaching out.</p>"},"attachments":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"File URL"},"name":{"type":"string","description":"File name"},"type":{"type":"string","description":"MIME type"},"assetId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Vault asset id backing this attachment"}},"required":["url","name","type"]},"maxItems":5,"description":"Optional file attachments"}},"required":["type","subject","content"],"title":"SendEmailOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["continueCall"]}},"required":["type"],"title":"ContinueCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["booking"]},"collect":{"type":"object","properties":{"email":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Email collection settings"},"address":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Address collection settings"}},"description":"Fields to collect during booking"}},"required":["type","collect"],"title":"BookingOutcome"}],"description":"Outcome configuration for the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID to link this scenario to","example":null}},"required":["name","prompt","response"]}}}},"responses":{"200":{"description":"Scenario created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]}},"required":["scenario"]}}}},"400":{"description":"Booking outcomes are not allowed on standalone scenarios","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Trade service not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Scenario with the same name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/scenarios/{scenarioId}":{"get":{"summary":"Get Scenario","description":"Retrieve a single scenario by ID, including questions and outcome. Only scenarios belonging to the organization associated with the API key can be retrieved.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the scenario","example":42},"required":false,"description":"The unique identifier of the scenario","name":"scenarioId","in":"path"}],"responses":{"200":{"description":"Successful response with scenario data","content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]}},"required":["scenario"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Scenario not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Scenario","description":"Update an existing scenario. Only scenarios belonging to the organization associated with the API key can be updated.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the scenario","example":42},"required":false,"description":"The unique identifier of the scenario","name":"scenarioId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","minLength":1,"description":"The prompt / instructions for the scenario","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","minLength":1,"description":"The response template for the scenario","example":"I would be happy to help you with pricing."},"isActive":{"type":"boolean","description":"Whether the scenario is active","example":true},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["transferCall"]},"transferId":{"type":"number","description":"The transfer ID linking to the transfer table","example":7},"method":{"type":"string","enum":["WARM","COLD"],"description":"Transfer method: WARM (with summary) or COLD (direct)","example":"WARM"}},"required":["type","transferId","method"],"title":"TransferCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendSMS"]},"content":{"type":"string","description":"SMS content to send","example":"Thank you for calling! Here is the information you requested."}},"required":["type","content"],"title":"SendSMSOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendEmail"]},"subject":{"type":"string","description":"Email subject line","example":"Follow-up from your call"},"content":{"type":"string","description":"Email body content (HTML supported)","example":"<p>Thank you for reaching out.</p>"},"attachments":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"File URL"},"name":{"type":"string","description":"File name"},"type":{"type":"string","description":"MIME type"},"assetId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Vault asset id backing this attachment"}},"required":["url","name","type"]},"maxItems":5,"description":"Optional file attachments"}},"required":["type","subject","content"],"title":"SendEmailOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["continueCall"]}},"required":["type"],"title":"ContinueCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["booking"]},"collect":{"type":"object","properties":{"email":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Email collection settings"},"address":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Address collection settings"}},"description":"Fields to collect during booking"}},"required":["type","collect"],"title":"BookingOutcome"}],"description":"Outcome configuration for the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID to link this scenario to","example":null}}}}}},"responses":{"200":{"description":"Scenario updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"scenario":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the scenario","example":42},"name":{"type":"string","description":"Name of the scenario","example":"Pricing Inquiry"},"prompt":{"type":"string","description":"The prompt / instructions that describe when and how this scenario should be triggered","example":"When a customer asks about pricing, follow this scenario."},"response":{"type":"string","description":"The response template the agent should follow for this scenario","example":"I would be happy to help you with pricing information. Let me walk you through our options."},"isActive":{"type":"boolean","nullable":true,"description":"Whether the scenario is active","example":true},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured set of questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Defines the final outcome after completing the scenario"},"tradeServiceId":{"type":"number","nullable":true,"description":"Optional trade service ID this scenario is linked to","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the scenario was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the scenario was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","name","prompt","response","isActive","questions","outcome","tradeServiceId","createdAt","updatedAt"]}},"required":["scenario"]}}}},"400":{"description":"Invalid request or newly attached asset exceeds 25 MB","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Scenario not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Scenario with the same name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Scenario","description":"Delete an existing scenario. Only scenarios belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["Scenarios"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the scenario","example":42},"required":false,"description":"The unique identifier of the scenario","name":"scenarioId","in":"path"}],"responses":{"200":{"description":"Scenario deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Scenario deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Scenario not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/services/{serviceId}":{"get":{"summary":"Get Service","description":"Retrieve a single trade service by ID, including its linked scenario. Only services belonging to the organization associated with the API key can be retrieved.","tags":["Services"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the service","example":123},"required":false,"description":"The unique identifier of the service","name":"serviceId","in":"path"}],"responses":{"200":{"description":"Successful response with service data","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the service","example":123},"name":{"type":"string","description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","description":"Description of the service","example":"Complete kitchen renovation and installation service"},"duration":{"type":"number","nullable":true,"description":"Service duration (stored in minutes)","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service","example":["What type of countertops do you prefer?","Do you need electrical work?"]},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":1},"pricingMode":{"type":"string","enum":["NONE","FIXED","HOURLY","RANGE"],"description":"The pricing mode for the service","example":"FIXED"},"fixedPrice":{"type":"number","nullable":true,"description":"Fixed price (when pricingMode is FIXED)","example":299.99},"hourlyRate":{"type":"number","nullable":true,"description":"Hourly rate (when pricingMode is HOURLY)","example":75},"callOutFee":{"type":"number","nullable":true,"description":"Call-out fee (when pricingMode is HOURLY)","example":50},"plusGST":{"type":"boolean","description":"Whether GST is added on top of the rate","example":false},"plusMaterials":{"type":"boolean","description":"Whether materials are charged separately","example":false},"minPrice":{"type":"number","nullable":true,"description":"Minimum price (when pricingMode is RANGE)","example":199.99},"maxPrice":{"type":"number","nullable":true,"description":"Maximum price (when pricingMode is RANGE)","example":499.99},"isCustomPriceResponseActive":{"type":"boolean","description":"Whether a custom price response is active","example":false},"customPriceResponse":{"type":"string","nullable":true,"description":"Custom price response text","example":null},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"isActive":{"type":"boolean","description":"Whether the service is active","example":true},"teamAssignmentMethod":{"type":"string","enum":["PRIORITY_ORDER","ROUND_ROBIN","LEAST_BUSY"],"description":"Method for assigning jobs to team members","example":"PRIORITY_ORDER"},"scenario":{"type":"object","nullable":true,"properties":{"id":{"type":"number","description":"Scenario ID","example":101},"response":{"type":"string","description":"AI response template for the scenario","example":""},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Outcome configuration for the scenario"}},"required":["id","response","questions","outcome"],"description":"The scenario linked to this service"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the service was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","duration","durationUnit","followUpQuestions","tradeCategoryId","pricingMode","fixedPrice","hourlyRate","callOutFee","plusGST","plusMaterials","minPrice","maxPrice","isCustomPriceResponseActive","customPriceResponse","isDisclosePrice","isActive","teamAssignmentMethod","scenario","createdAt","updatedAt"]}},"required":["service"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Service","description":"Update an existing trade service. Only services belonging to the organization associated with the API key can be updated.","tags":["Services"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the service","example":123},"required":false,"description":"The unique identifier of the service","name":"serviceId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","minLength":1,"description":"Description of the service","example":"Complete kitchen renovation and installation service"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service"},"duration":{"type":"number","nullable":true,"minimum":0,"description":"Service duration (stored in minutes)","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"tradeCategoryId":{"type":"number","nullable":true,"description":"Associated trade category ID","example":1},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"teamAssignmentMethod":{"type":"string","enum":["PRIORITY_ORDER","ROUND_ROBIN","LEAST_BUSY"],"description":"Method for assigning jobs to team members","example":"PRIORITY_ORDER"},"response":{"type":"string","maxLength":1000,"description":"AI response template for the scenario"},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["transferCall"]},"destinationType":{"type":"string","enum":["MEMBER","DEPARTMENT"],"description":"Transfer destination type (defaults to MEMBER for backward compatibility)","example":"MEMBER"},"memberId":{"type":"number","description":"Member ID (required when destinationType is MEMBER)","example":42},"departmentId":{"type":"string","description":"Department ID (required when destinationType is DEPARTMENT)"},"method":{"type":"string","enum":["WARM","COLD"],"description":"Transfer method: WARM (with summary) or COLD (direct)","example":"WARM"},"settings":{"type":"object","properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours for this transfer"}},"description":"Settings for the transfer"}},"required":["type"],"title":"ServiceTransferCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendSMS"]},"content":{"type":"string","minLength":1,"description":"SMS content to send","example":"Thank you for calling! Here is the information you requested."}},"required":["type","content"],"title":"ServiceSendSMSOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendEmail"]},"subject":{"type":"string","minLength":1,"description":"Email subject line","example":"Follow-up from your call"},"content":{"type":"string","minLength":1,"description":"Email body content (HTML supported)","example":"<p>Thank you for reaching out.</p>"},"attachments":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"File URL"},"name":{"type":"string","description":"File name"},"type":{"type":"string","description":"MIME type"},"size":{"type":"number","description":"File size in bytes","example":1024},"assetId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Vault asset id backing this attachment"}},"required":["url","name","type","size"]},"maxItems":5,"description":"Optional file attachments"}},"required":["type","subject","content"],"title":"ServiceSendEmailOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["continueCall"]}},"required":["type"],"title":"ServiceContinueCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["booking"]},"collect":{"type":"object","properties":{"email":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Email collection settings"},"address":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Address collection settings"}},"description":"Fields to collect during booking"}},"required":["type","collect"],"title":"ServiceBookingOutcome"}],"description":"Outcome configuration for the scenario"},"assignees":{"type":"array","items":{"type":"object","properties":{"memberId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Membership ID of the assigned team member","example":42},"priority":{"type":"integer","minimum":1,"default":1,"description":"Priority of the assignee (1 = highest)","example":1}},"required":["memberId"]},"minItems":1,"description":"List of team members assigned to this service"},"pricing":{"oneOf":[{"type":"object","properties":{"pricingMode":{"type":"string","enum":["NONE"]},"isCustomPriceResponseActive":{"type":"boolean","description":"Whether to use a custom response when price is asked","example":false},"customPriceResponse":{"type":"string","description":"Custom response to use when the customer asks about price","example":"Please contact us for a custom quote."}},"required":["pricingMode"],"title":"NonePricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["FIXED"]},"fixedPrice":{"type":"number","nullable":true,"minimum":0,"description":"Fixed price for the service","example":299.99}},"required":["pricingMode","fixedPrice"],"title":"FixedPricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["HOURLY"]},"hourlyRate":{"type":"number","nullable":true,"minimum":0,"description":"Hourly rate for the service","example":75},"callOutFee":{"type":"number","nullable":true,"minimum":0,"description":"Optional call-out fee","example":50},"plusGST":{"type":"boolean","default":false,"description":"Whether GST is added on top of the rate","example":false},"plusMaterials":{"type":"boolean","default":false,"description":"Whether materials are charged separately","example":false}},"required":["pricingMode","hourlyRate"],"title":"HourlyPricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["RANGE"]},"minPrice":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price for the range","example":199.99},"maxPrice":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price for the range","example":499.99}},"required":["pricingMode","minPrice","maxPrice"],"title":"RangePricing"}],"description":"Pricing configuration for the service"}},"description":"Request body for updating a service"}}}},"responses":{"200":{"description":"Service updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the service","example":123},"name":{"type":"string","description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","description":"Description of the service","example":"Complete kitchen renovation and installation service"},"duration":{"type":"number","nullable":true,"description":"Service duration (stored in minutes)","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service","example":["What type of countertops do you prefer?","Do you need electrical work?"]},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":1},"pricingMode":{"type":"string","enum":["NONE","FIXED","HOURLY","RANGE"],"description":"The pricing mode for the service","example":"FIXED"},"fixedPrice":{"type":"number","nullable":true,"description":"Fixed price (when pricingMode is FIXED)","example":299.99},"hourlyRate":{"type":"number","nullable":true,"description":"Hourly rate (when pricingMode is HOURLY)","example":75},"callOutFee":{"type":"number","nullable":true,"description":"Call-out fee (when pricingMode is HOURLY)","example":50},"plusGST":{"type":"boolean","description":"Whether GST is added on top of the rate","example":false},"plusMaterials":{"type":"boolean","description":"Whether materials are charged separately","example":false},"minPrice":{"type":"number","nullable":true,"description":"Minimum price (when pricingMode is RANGE)","example":199.99},"maxPrice":{"type":"number","nullable":true,"description":"Maximum price (when pricingMode is RANGE)","example":499.99},"isCustomPriceResponseActive":{"type":"boolean","description":"Whether a custom price response is active","example":false},"customPriceResponse":{"type":"string","nullable":true,"description":"Custom price response text","example":null},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"isActive":{"type":"boolean","description":"Whether the service is active","example":true},"teamAssignmentMethod":{"type":"string","enum":["PRIORITY_ORDER","ROUND_ROBIN","LEAST_BUSY"],"description":"Method for assigning jobs to team members","example":"PRIORITY_ORDER"},"scenario":{"type":"object","nullable":true,"properties":{"id":{"type":"number","description":"Scenario ID","example":101},"response":{"type":"string","description":"AI response template for the scenario","example":""},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Outcome configuration for the scenario"}},"required":["id","response","questions","outcome"],"description":"The scenario linked to this service"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the service was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","duration","durationUnit","followUpQuestions","tradeCategoryId","pricingMode","fixedPrice","hourlyRate","callOutFee","plusGST","plusMaterials","minPrice","maxPrice","isCustomPriceResponseActive","customPriceResponse","isDisclosePrice","isActive","teamAssignmentMethod","scenario","createdAt","updatedAt"]}},"required":["service"]}}}},"400":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"A service with the same name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Service","description":"Soft-delete an existing trade service. Associated assignees, scenario, and transfer records are removed. Only services belonging to the organization associated with the API key can be deleted.","tags":["Services"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the service","example":123},"required":false,"description":"The unique identifier of the service","name":"serviceId","in":"path"}],"responses":{"200":{"description":"Service deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Service deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/services":{"post":{"summary":"Create Service","description":"Create a new trade service. The service will be associated with the organization of the API key. A scenario is automatically created and linked to the service.","tags":["Services"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","minLength":1,"description":"Description of the service","example":"Complete kitchen renovation and installation service"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service","example":[]},"duration":{"type":"number","nullable":true,"minimum":0,"description":"Service duration (stored in minutes)","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"tradeCategoryId":{"type":"number","nullable":true,"description":"Associated trade category ID","example":1},"isDisclosePrice":{"type":"boolean","default":true,"description":"Whether Sophiie can disclose the price to the customer","example":true},"teamAssignmentMethod":{"type":"string","enum":["PRIORITY_ORDER","ROUND_ROBIN","LEAST_BUSY"],"default":"PRIORITY_ORDER","description":"Method for assigning jobs to team members","example":"PRIORITY_ORDER"},"response":{"type":"string","maxLength":1000,"default":"","description":"AI response template for the scenario","example":""},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"default":[],"description":"Structured questions with answer options and follow-ups"},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["transferCall"]},"destinationType":{"type":"string","enum":["MEMBER","DEPARTMENT"],"description":"Transfer destination type (defaults to MEMBER for backward compatibility)","example":"MEMBER"},"memberId":{"type":"number","description":"Member ID (required when destinationType is MEMBER)","example":42},"departmentId":{"type":"string","description":"Department ID (required when destinationType is DEPARTMENT)"},"method":{"type":"string","enum":["WARM","COLD"],"description":"Transfer method: WARM (with summary) or COLD (direct)","example":"WARM"},"settings":{"type":"object","properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours for this transfer"}},"description":"Settings for the transfer"}},"required":["type"],"title":"ServiceTransferCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendSMS"]},"content":{"type":"string","minLength":1,"description":"SMS content to send","example":"Thank you for calling! Here is the information you requested."}},"required":["type","content"],"title":"ServiceSendSMSOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendEmail"]},"subject":{"type":"string","minLength":1,"description":"Email subject line","example":"Follow-up from your call"},"content":{"type":"string","minLength":1,"description":"Email body content (HTML supported)","example":"<p>Thank you for reaching out.</p>"},"attachments":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"File URL"},"name":{"type":"string","description":"File name"},"type":{"type":"string","description":"MIME type"},"size":{"type":"number","description":"File size in bytes","example":1024},"assetId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Vault asset id backing this attachment"}},"required":["url","name","type","size"]},"maxItems":5,"description":"Optional file attachments"}},"required":["type","subject","content"],"title":"ServiceSendEmailOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["continueCall"]}},"required":["type"],"title":"ServiceContinueCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["booking"]},"collect":{"type":"object","properties":{"email":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Email collection settings"},"address":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Address collection settings"}},"description":"Fields to collect during booking"}},"required":["type","collect"],"title":"ServiceBookingOutcome"}],"default":{"type":"continueCall"},"description":"Outcome configuration for the scenario"},"assignees":{"type":"array","items":{"type":"object","properties":{"memberId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Membership ID of the assigned team member","example":42},"priority":{"type":"integer","minimum":1,"default":1,"description":"Priority of the assignee (1 = highest)","example":1}},"required":["memberId"]},"minItems":1,"description":"List of team members assigned to this service"}},"required":["name","description","followUpQuestions","duration","durationUnit","tradeCategoryId"]},{"oneOf":[{"type":"object","properties":{"pricingMode":{"type":"string","enum":["NONE"]},"isCustomPriceResponseActive":{"type":"boolean","description":"Whether to use a custom response when price is asked","example":false},"customPriceResponse":{"type":"string","description":"Custom response to use when the customer asks about price","example":"Please contact us for a custom quote."}},"required":["pricingMode"],"title":"NonePricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["FIXED"]},"fixedPrice":{"type":"number","nullable":true,"minimum":0,"description":"Fixed price for the service","example":299.99}},"required":["pricingMode","fixedPrice"],"title":"FixedPricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["HOURLY"]},"hourlyRate":{"type":"number","nullable":true,"minimum":0,"description":"Hourly rate for the service","example":75},"callOutFee":{"type":"number","nullable":true,"minimum":0,"description":"Optional call-out fee","example":50},"plusGST":{"type":"boolean","default":false,"description":"Whether GST is added on top of the rate","example":false},"plusMaterials":{"type":"boolean","default":false,"description":"Whether materials are charged separately","example":false}},"required":["pricingMode","hourlyRate"],"title":"HourlyPricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["RANGE"]},"minPrice":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price for the range","example":199.99},"maxPrice":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price for the range","example":499.99}},"required":["pricingMode","minPrice","maxPrice"],"title":"RangePricing"}],"description":"Pricing configuration. Shape depends on `pricingMode`: NONE, FIXED, HOURLY, RANGE."}],"description":"Request body for creating a service"}}}},"responses":{"200":{"description":"Service created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the service","example":123},"name":{"type":"string","description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","description":"Description of the service","example":"Complete kitchen renovation and installation service"},"duration":{"type":"number","nullable":true,"description":"Service duration (stored in minutes)","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service","example":["What type of countertops do you prefer?","Do you need electrical work?"]},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":1},"pricingMode":{"type":"string","enum":["NONE","FIXED","HOURLY","RANGE"],"description":"The pricing mode for the service","example":"FIXED"},"fixedPrice":{"type":"number","nullable":true,"description":"Fixed price (when pricingMode is FIXED)","example":299.99},"hourlyRate":{"type":"number","nullable":true,"description":"Hourly rate (when pricingMode is HOURLY)","example":75},"callOutFee":{"type":"number","nullable":true,"description":"Call-out fee (when pricingMode is HOURLY)","example":50},"plusGST":{"type":"boolean","description":"Whether GST is added on top of the rate","example":false},"plusMaterials":{"type":"boolean","description":"Whether materials are charged separately","example":false},"minPrice":{"type":"number","nullable":true,"description":"Minimum price (when pricingMode is RANGE)","example":199.99},"maxPrice":{"type":"number","nullable":true,"description":"Maximum price (when pricingMode is RANGE)","example":499.99},"isCustomPriceResponseActive":{"type":"boolean","description":"Whether a custom price response is active","example":false},"customPriceResponse":{"type":"string","nullable":true,"description":"Custom price response text","example":null},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"isActive":{"type":"boolean","description":"Whether the service is active","example":true},"teamAssignmentMethod":{"type":"string","enum":["PRIORITY_ORDER","ROUND_ROBIN","LEAST_BUSY"],"description":"Method for assigning jobs to team members","example":"PRIORITY_ORDER"},"scenario":{"type":"object","nullable":true,"properties":{"id":{"type":"number","description":"Scenario ID","example":101},"response":{"type":"string","description":"AI response template for the scenario","example":""},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Outcome configuration for the scenario"}},"required":["id","response","questions","outcome"],"description":"The scenario linked to this service"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the service was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","duration","durationUnit","followUpQuestions","tradeCategoryId","pricingMode","fixedPrice","hourlyRate","callOutFee","plusGST","plusMaterials","minPrice","maxPrice","isCustomPriceResponseActive","customPriceResponse","isDisclosePrice","isActive","teamAssignmentMethod","scenario","createdAt","updatedAt"]}},"required":["service"]}}}},"400":{"description":"Bad request - trade category not found, invalid assignees, or pricing configuration invalid","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Attachment references an asset not in this organization","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"A service with the same name already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/services/batch":{"patch":{"summary":"Batch Update Services","description":"Update up to 100 trade services in one request. Items are processed sequentially and failures are reported per item without rolling back successful updates.","tags":["Services"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the service to update","example":123},"name":{"type":"string","minLength":1,"maxLength":100,"description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","minLength":1,"description":"Description of the service","example":"Complete kitchen renovation and installation service"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service"},"duration":{"type":"number","nullable":true,"minimum":0,"description":"Service duration (stored in minutes)","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"tradeCategoryId":{"type":"number","nullable":true,"description":"Associated trade category ID","example":1},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"teamAssignmentMethod":{"type":"string","enum":["PRIORITY_ORDER","ROUND_ROBIN","LEAST_BUSY"],"description":"Method for assigning jobs to team members","example":"PRIORITY_ORDER"},"response":{"type":"string","maxLength":1000,"description":"AI response template for the scenario"},"questions":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["transferCall"]},"destinationType":{"type":"string","enum":["MEMBER","DEPARTMENT"],"description":"Transfer destination type (defaults to MEMBER for backward compatibility)","example":"MEMBER"},"memberId":{"type":"number","description":"Member ID (required when destinationType is MEMBER)","example":42},"departmentId":{"type":"string","description":"Department ID (required when destinationType is DEPARTMENT)"},"method":{"type":"string","enum":["WARM","COLD"],"description":"Transfer method: WARM (with summary) or COLD (direct)","example":"WARM"},"settings":{"type":"object","properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours for this transfer"}},"description":"Settings for the transfer"}},"required":["type"],"title":"ServiceTransferCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendSMS"]},"content":{"type":"string","minLength":1,"description":"SMS content to send","example":"Thank you for calling! Here is the information you requested."}},"required":["type","content"],"title":"ServiceSendSMSOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["sendEmail"]},"subject":{"type":"string","minLength":1,"description":"Email subject line","example":"Follow-up from your call"},"content":{"type":"string","minLength":1,"description":"Email body content (HTML supported)","example":"<p>Thank you for reaching out.</p>"},"attachments":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"File URL"},"name":{"type":"string","description":"File name"},"type":{"type":"string","description":"MIME type"},"size":{"type":"number","description":"File size in bytes","example":1024},"assetId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Vault asset id backing this attachment"}},"required":["url","name","type","size"]},"maxItems":5,"description":"Optional file attachments"}},"required":["type","subject","content"],"title":"ServiceSendEmailOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["continueCall"]}},"required":["type"],"title":"ServiceContinueCallOutcome"},{"type":"object","properties":{"type":{"type":"string","enum":["booking"]},"collect":{"type":"object","properties":{"email":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Email collection settings"},"address":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this field is enabled"},"confirm":{"type":"boolean","description":"Whether to confirm this field with the caller"}},"required":["enabled"],"description":"Address collection settings"}},"description":"Fields to collect during booking"}},"required":["type","collect"],"title":"ServiceBookingOutcome"}],"description":"Outcome configuration for the scenario"},"assignees":{"type":"array","items":{"type":"object","properties":{"memberId":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Membership ID of the assigned team member","example":42},"priority":{"type":"integer","minimum":1,"default":1,"description":"Priority of the assignee (1 = highest)","example":1}},"required":["memberId"]},"minItems":1,"description":"List of team members assigned to this service"},"pricing":{"oneOf":[{"type":"object","properties":{"pricingMode":{"type":"string","enum":["NONE"]},"isCustomPriceResponseActive":{"type":"boolean","description":"Whether to use a custom response when price is asked","example":false},"customPriceResponse":{"type":"string","description":"Custom response to use when the customer asks about price","example":"Please contact us for a custom quote."}},"required":["pricingMode"],"title":"NonePricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["FIXED"]},"fixedPrice":{"type":"number","nullable":true,"minimum":0,"description":"Fixed price for the service","example":299.99}},"required":["pricingMode","fixedPrice"],"title":"FixedPricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["HOURLY"]},"hourlyRate":{"type":"number","nullable":true,"minimum":0,"description":"Hourly rate for the service","example":75},"callOutFee":{"type":"number","nullable":true,"minimum":0,"description":"Optional call-out fee","example":50},"plusGST":{"type":"boolean","default":false,"description":"Whether GST is added on top of the rate","example":false},"plusMaterials":{"type":"boolean","default":false,"description":"Whether materials are charged separately","example":false}},"required":["pricingMode","hourlyRate"],"title":"HourlyPricing"},{"type":"object","properties":{"pricingMode":{"type":"string","enum":["RANGE"]},"minPrice":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price for the range","example":199.99},"maxPrice":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price for the range","example":499.99}},"required":["pricingMode","minPrice","maxPrice"],"title":"RangePricing"}],"description":"Pricing configuration for the service"}},"required":["id"],"description":"One service update in the batch","example":{"id":123,"pricing":{"pricingMode":"FIXED","fixedPrice":299},"duration":120,"durationUnit":"MINUTES"}},"minItems":1,"maxItems":100,"description":"Service updates to process sequentially. Maximum 100."}},"required":["updates"],"description":"Request body for updating services in a batch","example":{"updates":[{"id":123,"pricing":{"pricingMode":"FIXED","fixedPrice":299},"duration":120,"durationUnit":"MINUTES"},{"id":124,"name":"Renamed service"}]}}}}},"responses":{"200":{"description":"Batch processed successfully, including partial failures","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"number","description":"Service ID from the request item","example":123},"status":{"type":"string","enum":["ok"],"description":"Per-item update status","example":"ok"},"service":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the service","example":123},"name":{"type":"string","description":"Name of the service","example":"Kitchen Installation"},"description":{"type":"string","description":"Description of the service","example":"Complete kitchen renovation and installation service"},"duration":{"type":"number","nullable":true,"description":"Service duration (stored in minutes)","example":180},"durationUnit":{"type":"string","enum":["MINUTES","HOURS","DAYS"],"description":"Duration unit for display purposes","example":"MINUTES"},"followUpQuestions":{"type":"array","items":{"type":"string"},"description":"Follow-up questions for this service","example":["What type of countertops do you prefer?","Do you need electrical work?"]},"tradeCategoryId":{"type":"number","description":"Associated trade category ID","example":1},"pricingMode":{"type":"string","enum":["NONE","FIXED","HOURLY","RANGE"],"description":"The pricing mode for the service","example":"FIXED"},"fixedPrice":{"type":"number","nullable":true,"description":"Fixed price (when pricingMode is FIXED)","example":299.99},"hourlyRate":{"type":"number","nullable":true,"description":"Hourly rate (when pricingMode is HOURLY)","example":75},"callOutFee":{"type":"number","nullable":true,"description":"Call-out fee (when pricingMode is HOURLY)","example":50},"plusGST":{"type":"boolean","description":"Whether GST is added on top of the rate","example":false},"plusMaterials":{"type":"boolean","description":"Whether materials are charged separately","example":false},"minPrice":{"type":"number","nullable":true,"description":"Minimum price (when pricingMode is RANGE)","example":199.99},"maxPrice":{"type":"number","nullable":true,"description":"Maximum price (when pricingMode is RANGE)","example":499.99},"isCustomPriceResponseActive":{"type":"boolean","description":"Whether a custom price response is active","example":false},"customPriceResponse":{"type":"string","nullable":true,"description":"Custom price response text","example":null},"isDisclosePrice":{"type":"boolean","description":"Whether Sophiie can disclose the price to the customer","example":true},"isActive":{"type":"boolean","description":"Whether the service is active","example":true},"teamAssignmentMethod":{"type":"string","enum":["PRIORITY_ORDER","ROUND_ROBIN","LEAST_BUSY"],"description":"Method for assigning jobs to team members","example":"PRIORITY_ORDER"},"scenario":{"type":"object","nullable":true,"properties":{"id":{"type":"number","description":"Scenario ID","example":101},"response":{"type":"string","description":"AI response template for the scenario","example":""},"questions":{"type":"array","nullable":true,"items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Question text","example":"Are you an existing customer?"},"answerOptions":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string","minLength":1,"description":"Answer option text","example":"Yes"},"followUps":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":1,"description":"Follow-up question text","example":"Can you tell me more about that?"}},"required":["question"]},"description":"Follow-up questions for this answer option"}},"required":["answer","followUps"]},"description":"Possible answer options with follow-ups"}},"required":["question","answerOptions"]},"description":"Structured questions with answer options and follow-ups"},"outcome":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["transferCall","sendSMS","sendEmail","continueCall","booking"],"description":"The type of outcome after completing the scenario","example":"continueCall"}},"required":["type"],"additionalProperties":{"nullable":true},"description":"Outcome configuration for the scenario"}},"required":["id","response","questions","outcome"],"description":"The scenario linked to this service"},"createdAt":{"type":"string","description":"Creation timestamp (ISO 8601)","example":"2023-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the service was last updated","example":"2023-01-20T14:00:00.000Z"}},"required":["id","name","description","duration","durationUnit","followUpQuestions","tradeCategoryId","pricingMode","fixedPrice","hourlyRate","callOutFee","plusGST","plusMaterials","minPrice","maxPrice","isCustomPriceResponseActive","customPriceResponse","isDisclosePrice","isActive","teamAssignmentMethod","scenario","createdAt","updatedAt"]}},"required":["id","status","service"]},{"type":"object","properties":{"id":{"type":"number","description":"Service ID from the request item","example":124},"status":{"type":"string","enum":["error"],"description":"Per-item update status","example":"error"},"code":{"type":"string","enum":["NOT_FOUND","INVALID_CATEGORY","INVALID_DESTINATION","DUPLICATE_NAME","CONFLICT","ATTACHMENT_TOO_LARGE","INTERNAL_ERROR"],"description":"Machine-readable per-item error code","example":"NOT_FOUND"},"message":{"type":"string","description":"Human-readable per-item error message","example":"Service not found"}},"required":["id","status","code","message"]}]},"description":"Per-item update results in request order"},"summary":{"type":"object","properties":{"total":{"type":"number","description":"Total number of requested updates","example":2},"succeeded":{"type":"number","description":"Number of successful updates","example":1},"failed":{"type":"number","description":"Number of failed updates","example":1}},"required":["total","succeeded","failed"]}},"required":["results","summary"],"description":"Batch service update response","example":{"results":[{"id":123,"status":"ok","service":{"id":123,"name":"Kitchen Installation","description":"Complete kitchen renovation and installation service","duration":120,"durationUnit":"MINUTES","followUpQuestions":[],"tradeCategoryId":1,"pricingMode":"FIXED","fixedPrice":299,"hourlyRate":null,"callOutFee":null,"plusGST":false,"plusMaterials":false,"minPrice":null,"maxPrice":null,"isCustomPriceResponseActive":false,"customPriceResponse":null,"isDisclosePrice":true,"isActive":true,"teamAssignmentMethod":"PRIORITY_ORDER","scenario":null,"createdAt":"2023-01-01T00:00:00.000Z","updatedAt":"2023-01-20T14:00:00.000Z"}},{"id":124,"status":"error","code":"NOT_FOUND","message":"Service not found"}],"summary":{"total":2,"succeeded":1,"failed":1}}}}}},"400":{"description":"Bad request - malformed body or batch size exceeds 100","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Batch size exceeds maximum of 100 items"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"code":{"type":"string","enum":["BATCH_TOO_LARGE"],"description":"Machine-readable error code","example":"BATCH_TOO_LARGE"},"message":{"type":"string","description":"Error message","example":"Batch size exceeds maximum of 100 items"}},"required":["status","code","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/sms":{"post":{"summary":"Send SMS","description":"Send an SMS message to a lead. The SMS will be associated with the organization of the API key. If messageThreadId is not provided, a new message thread and inquiry will be created.","tags":["SMS"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","description":"Deprecated and ignored. The sending user is derived from the organization's active membership; a value supplied here has no effect on attribution. Retained so existing integrations keep validating.","example":"usr_abc123","deprecated":true},"leadId":{"type":"string","description":"Unique identifier for the lead","example":"ld_abc123"},"message":{"type":"string","description":"SMS message content (required for plain SMS, optional for MMS with mediaUrls)","example":"How are you?"},"messageThreadId":{"type":"number","description":"Optional message thread ID to continue an existing conversation","example":12345},"mediaUrls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10,"description":"Optional array of publicly accessible HTTPS URLs for MMS media attachments (max 10, total 5MB)","example":["https://example.com/photo.jpg"]}},"required":["userId","leadId"]}}}},"responses":{"200":{"description":"SMS sent successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Message sent successfully"}},"required":["message"]}}}},"400":{"description":"Bad request - Invalid input or SMS delivery failure","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"403":{"description":"Forbidden - SMS requires a paid plan or the subscription is paused / past due","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/transfers":{"get":{"summary":"List Transfers","description":"Retrieve a paginated list of transfer rules. Returns transfer data including label, method, destination, conditions, and settings. Results are filtered by the organization associated with the API key.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number for pagination","example":1},"required":false,"description":"Page number for pagination","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Number of items per page (max 100)","example":50},"required":false,"description":"Number of items per page (max 100)","name":"limit","in":"query"}],"responses":{"200":{"description":"Successful response with paginated transfer data","content":{"application/json":{"schema":{"type":"object","properties":{"transfers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]},"description":"Array of transfers"},"totalPages":{"type":"number","description":"Total number of pages available","example":2},"currentPage":{"type":"number","description":"Current page number","example":1},"totalCount":{"type":"number","description":"Total number of transfers","example":15}},"required":["transfers","totalPages","currentPage","totalCount"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"post":{"summary":"Create Transfer","description":"Create a new transfer rule. The transfer will be associated with the organization of the API key.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":255,"description":"Label for the transfer rule","example":"Sales Department Transfer"},"name":{"type":"string","minLength":1,"maxLength":255,"description":"Display name of the phone transfer destination. Required when destinationType is PHONE; omit when destinationType is DEPARTMENT or MEMBER.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination","example":"DEPARTMENT"},"destination":{"type":"string","minLength":1,"maxLength":255,"description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","minLength":1,"description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":null},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled (defaults to true)","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario to link this transfer to","example":null}},"required":["label","method","destinationType","destination","conditions"]}}}},"responses":{"200":{"description":"Transfer created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transfer":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]}},"required":["transfer"]}}}},"400":{"description":"Invalid or inaccessible scenario","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Transfer with the same label already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}},"/v1/transfers/{transferId}":{"get":{"summary":"Get Transfer","description":"Retrieve a single transfer rule by ID. Only transfers belonging to the organization associated with the API key can be retrieved.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the transfer","example":7},"required":false,"description":"The unique identifier of the transfer","name":"transferId","in":"path"}],"responses":{"200":{"description":"Successful response with transfer data","content":{"application/json":{"schema":{"type":"object","properties":{"transfer":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]}},"required":["transfer"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Transfer not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"put":{"summary":"Update Transfer","description":"Update an existing transfer rule. Only transfers belonging to the organization associated with the API key can be updated.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the transfer","example":7},"required":false,"description":"The unique identifier of the transfer","name":"transferId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":255,"description":"Label for the transfer rule","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"maxLength":255,"description":"Display name of the phone transfer destination. Only used when destinationType is PHONE; set to null or omit for DEPARTMENT or MEMBER.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination","example":"DEPARTMENT"},"destination":{"type":"string","minLength":1,"maxLength":255,"description":"Destination identifier","example":"dep_sales_01"},"conditions":{"type":"string","minLength":1,"description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message","example":null},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario to link this transfer to","example":null}}}}}},"responses":{"200":{"description":"Transfer updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"transfer":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the transfer","example":7},"label":{"type":"string","minLength":2,"maxLength":255,"description":"Label for the transfer rule, so that you can identify it","example":"Sales Department Transfer"},"name":{"type":"string","nullable":true,"description":"Display name of the phone transfer destination. Only set when destinationType is PHONE; otherwise null.","example":"Sales Team"},"method":{"type":"string","enum":["COLD","WARM"],"description":"Transfer method — COLD (direct pass) or WARM (with summary to transferee)","example":"WARM"},"destinationType":{"type":"string","enum":["DEPARTMENT","MEMBER","PHONE"],"description":"Type of transfer destination — a department, an individual member, or a phone number","example":"DEPARTMENT"},"destination":{"type":"string","description":"Destination identifier. Department ID (dep_*), member ID (numeric), phone (tel:*), or SIP URI (sip:*)","example":"dep_sales_01"},"conditions":{"type":"string","description":"Conditions that trigger this transfer","example":"When the customer asks to speak with a sales representative."},"summaryFormat":{"type":"string","nullable":true,"description":"Format for the warm transfer summary message (null for cold transfers)","example":"Customer {name} is calling about {topic}. Key details: {summary}."},"settings":{"type":"object","nullable":true,"properties":{"ignore_business_hours":{"type":"boolean","description":"Whether to ignore business hours when routing this transfer","example":false}},"required":["ignore_business_hours"],"description":"Transfer-specific settings"},"isEnabled":{"type":"boolean","description":"Whether this transfer rule is enabled","example":true},"scenarioId":{"type":"number","nullable":true,"description":"ID of the scenario this transfer is linked to (null if standalone)","example":null},"createdAt":{"type":"string","description":"ISO 8601 timestamp of when the transfer was created","example":"2026-01-15T10:30:00.000Z"},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of when the transfer was last updated","example":"2026-01-20T14:00:00.000Z"}},"required":["id","label","name","method","destinationType","destination","conditions","summaryFormat","settings","isEnabled","scenarioId","createdAt","updatedAt"]}},"required":["transfer"]}}}},"400":{"description":"Invalid or inaccessible scenario","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Bad request"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":400},"message":{"type":"string","description":"Error message","example":"Bad request"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Transfer not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"409":{"description":"Transfer with the same label already exists","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Conflict"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":409},"message":{"type":"string","description":"Error message","example":"Conflict"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}},"delete":{"summary":"Delete Transfer","description":"Delete an existing transfer rule. Only transfers belonging to the organization associated with the API key can be deleted. This performs a soft delete.","tags":["Transfers"],"security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"number","nullable":true,"description":"The unique identifier of the transfer","example":7},"required":false,"description":"The unique identifier of the transfer","name":"transferId","in":"path"}],"responses":{"200":{"description":"Transfer deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message","example":"Transfer deleted successfully"}},"required":["message"]}}}},"401":{"description":"Unauthorized - Invalid or missing access token","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":401},"message":{"type":"string","description":"Error message","example":"Invalid or expired token"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"404":{"description":"Transfer not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Not found"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":404},"message":{"type":"string","description":"Error message","example":"Not found"}},"required":["status","message"]}},"required":["success","message","error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Success status","example":false},"message":{"type":"string","description":"Error message","example":"Internal server error"},"error":{"type":"object","properties":{"status":{"type":"number","description":"HTTP status code","example":500},"message":{"type":"string","description":"Error message","example":"Internal server error"}},"required":["status","message"]}},"required":["success","message","error"]}}}}}}}}}