{ "openapi": "3.1.0", "info": { "title": "Comfort Care Public API", "version": "1.0.0", "description": "The Comfort Care public API.\n\n**Authentication.** Send an API token as `Authorization: Bearer `.\nEvery request resolves its tenant from the credential — there is no tenant\nparameter anywhere in this API, and supplying one has no effect.\n\n**Authorization.** A token's scopes narrow what it may do; they never widen\nit. The effective permission is the intersection of the token's scopes, the\nRBAC permissions of the identity it acts for, and tenant isolation.\n\n**Errors.** Every failure returns the same shape. `code` is the stable\ncontract; `message` is for humans and may be reworded without notice.", "contact": { "name": "Comfort Care Platform Operations" } }, "servers": [ { "url": "https://api.comfortcare.cloud", "description": "Current environment" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Customer", "description": "People receiving care." }, { "name": "CarePlan", "description": "The agreed plan of care for a customer." }, { "name": "Appointment", "description": "Scheduled care appointments." }, { "name": "Visit", "description": "Executed care visits." }, { "name": "Invoice", "description": "Issued and draft invoices." }, { "name": "Payment", "description": "Payments recorded against invoices." }, { "name": "Document", "description": "Documents attached to a customer or care plan." }, { "name": "Notification", "description": "Notifications raised by the platform." }, { "name": "ReportDefinition", "description": "Reports available to run. Executing one is a separate call." }, { "name": "Workflow", "description": "Automation workflows defined for the tenant." } ], "paths": { "/api/v1/customers": { "get": { "tags": [ "Customer" ], "summary": "List Customer records", "description": "People receiving care.\n\nRequires the `customers.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listCustomer", "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: display_name, created_at, updated_at, status.", "schema": { "type": "string", "enum": [ "display_name", "-display_name", "created_at", "-created_at", "updated_at", "-updated_at", "status", "-status" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `display_name`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by `status` (exact match).", "schema": { "type": "string" } }, { "name": "preferred_language_code", "in": "query", "description": "Filter by `preferred_language_code` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Customer records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/customers/{id}": { "get": { "tags": [ "Customer" ], "summary": "Retrieve one Customer", "description": "People receiving care.\n\nRequires the `customers.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getCustomer", "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Customer.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/care-plans": { "get": { "tags": [ "CarePlan" ], "summary": "List CarePlan records", "description": "The agreed plan of care for a customer.\n\nRequires the `customers.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listCarePlan", "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: created_at, updated_at, start_date, next_review_date, status.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "start_date", "-start_date", "next_review_date", "-next_review_date", "status", "-status" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `title`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by `status` (exact match).", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter by `customer_id` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of CarePlan records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CarePlan" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/care-plans/{id}": { "get": { "tags": [ "CarePlan" ], "summary": "Retrieve one CarePlan", "description": "The agreed plan of care for a customer.\n\nRequires the `customers.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getCarePlan", "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested CarePlan.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CarePlan" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/appointments": { "get": { "tags": [ "Appointment" ], "summary": "List Appointment records", "description": "Scheduled care appointments.\n\nRequires the `appointments.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listAppointment", "security": [ { "bearerAuth": [ "appointments.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: scheduled_start, scheduled_end, created_at, status.", "schema": { "type": "string", "enum": [ "scheduled_start", "-scheduled_start", "scheduled_end", "-scheduled_end", "created_at", "-created_at", "status", "-status" ] } }, { "name": "status", "in": "query", "description": "Filter by `status` (exact match).", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter by `customer_id` (exact match).", "schema": { "type": "string" } }, { "name": "care_plan_id", "in": "query", "description": "Filter by `care_plan_id` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Appointment records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Appointment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/appointments/{id}": { "get": { "tags": [ "Appointment" ], "summary": "Retrieve one Appointment", "description": "Scheduled care appointments.\n\nRequires the `appointments.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getAppointment", "security": [ { "bearerAuth": [ "appointments.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Appointment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Appointment" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/visits": { "get": { "tags": [ "Visit" ], "summary": "List Visit records", "description": "Executed care visits.\n\nRequires the `visits.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listVisit", "security": [ { "bearerAuth": [ "visits.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: checked_in_at, checked_out_at, created_at, status.", "schema": { "type": "string", "enum": [ "checked_in_at", "-checked_in_at", "checked_out_at", "-checked_out_at", "created_at", "-created_at", "status", "-status" ] } }, { "name": "status", "in": "query", "description": "Filter by `status` (exact match).", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter by `customer_id` (exact match).", "schema": { "type": "string" } }, { "name": "appointment_id", "in": "query", "description": "Filter by `appointment_id` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Visit records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Visit" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/visits/{id}": { "get": { "tags": [ "Visit" ], "summary": "Retrieve one Visit", "description": "Executed care visits.\n\nRequires the `visits.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getVisit", "security": [ { "bearerAuth": [ "visits.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Visit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Visit" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/invoices": { "get": { "tags": [ "Invoice" ], "summary": "List Invoice records", "description": "Issued and draft invoices.\n\nRequires the `billing.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listInvoice", "security": [ { "bearerAuth": [ "billing.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: issue_date, due_date, created_at, total, status.", "schema": { "type": "string", "enum": [ "issue_date", "-issue_date", "due_date", "-due_date", "created_at", "-created_at", "total", "-total", "status", "-status" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `invoice_number`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by `status` (exact match).", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter by `customer_id` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Invoice records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/invoices/{id}": { "get": { "tags": [ "Invoice" ], "summary": "Retrieve one Invoice", "description": "Issued and draft invoices.\n\nRequires the `billing.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getInvoice", "security": [ { "bearerAuth": [ "billing.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Invoice.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Invoice" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payments": { "get": { "tags": [ "Payment" ], "summary": "List Payment records", "description": "Payments recorded against invoices.\n\nRequires the `billing.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listPayment", "security": [ { "bearerAuth": [ "billing.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: received_at, created_at, amount.", "schema": { "type": "string", "enum": [ "received_at", "-received_at", "created_at", "-created_at", "amount", "-amount" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `reference`.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter by `customer_id` (exact match).", "schema": { "type": "string" } }, { "name": "method", "in": "query", "description": "Filter by `method` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Payment records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payments/{id}": { "get": { "tags": [ "Payment" ], "summary": "Retrieve one Payment", "description": "Payments recorded against invoices.\n\nRequires the `billing.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getPayment", "security": [ { "bearerAuth": [ "billing.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Payment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/documents": { "get": { "tags": [ "Document" ], "summary": "List Document records", "description": "Documents attached to a customer or care plan.\n\nRequires the `customers.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listDocument", "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: created_at, updated_at, title.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "title", "-title" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `title`.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter by `customer_id` (exact match).", "schema": { "type": "string" } }, { "name": "care_plan_id", "in": "query", "description": "Filter by `care_plan_id` (exact match).", "schema": { "type": "string" } }, { "name": "category_id", "in": "query", "description": "Filter by `category_id` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Document records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/documents/{id}": { "get": { "tags": [ "Document" ], "summary": "Retrieve one Document", "description": "Documents attached to a customer or care plan.\n\nRequires the `customers.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getDocument", "security": [ { "bearerAuth": [ "customers.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Document.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Document" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/notifications": { "get": { "tags": [ "Notification" ], "summary": "List Notification records", "description": "Notifications raised by the platform.\n\nRequires the `notifications.send` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listNotification", "security": [ { "bearerAuth": [ "notifications.send" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: created_at, category.", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "category", "-category" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `title`.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by `category` (exact match).", "schema": { "type": "string" } }, { "name": "related_entity_type", "in": "query", "description": "Filter by `related_entity_type` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Notification records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/notifications/{id}": { "get": { "tags": [ "Notification" ], "summary": "Retrieve one Notification", "description": "Notifications raised by the platform.\n\nRequires the `notifications.send` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getNotification", "security": [ { "bearerAuth": [ "notifications.send" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Notification.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Notification" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/reports": { "get": { "tags": [ "ReportDefinition" ], "summary": "List ReportDefinition records", "description": "Reports available to run. Executing one is a separate call.\n\nRequires the `reports.read` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listReportDefinition", "security": [ { "bearerAuth": [ "reports.read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: code, name, category.", "schema": { "type": "string", "enum": [ "code", "-code", "name", "-name", "category", "-category" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `name`.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by `category` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of ReportDefinition records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportDefinition" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/reports/{id}": { "get": { "tags": [ "ReportDefinition" ], "summary": "Retrieve one ReportDefinition", "description": "Reports available to run. Executing one is a separate call.\n\nRequires the `reports.read` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getReportDefinition", "security": [ { "bearerAuth": [ "reports.read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested ReportDefinition.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ReportDefinition" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workflows": { "get": { "tags": [ "Workflow" ], "summary": "List Workflow records", "description": "Automation workflows defined for the tenant.\n\nRequires the `workflow.execute` scope, and the acting identity must also hold the RBAC permission that scope maps to.", "operationId": "listWorkflow", "security": [ { "bearerAuth": [ "workflow.execute" ] } ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" }, { "name": "sort", "in": "query", "description": "Sort field. Prefix with `-` for descending. Allowed: code, name, created_at, status.", "schema": { "type": "string", "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "status", "-status" ] } }, { "name": "q", "in": "query", "description": "Free-text search over `name`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by `status` (exact match).", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by `category` (exact match).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of Workflow records.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workflows/{id}": { "get": { "tags": [ "Workflow" ], "summary": "Retrieve one Workflow", "description": "Automation workflows defined for the tenant.\n\nRequires the `workflow.execute` scope. A record belonging to another tenant is reported as 404, not 403 — distinguishing the two would confirm it exists.", "operationId": "getWorkflow", "security": [ { "bearerAuth": [ "workflow.execute" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The requested Workflow.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Workflow" } } } } } }, "401": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential does not grant the required scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API token issued by the tenant (`cc_pat_…` or `cc_tok_…`). Tenant API keys are not accepted on resource endpoints — they are not bound to a user, and every resource query runs under that user's row-level security." } }, "parameters": { "Limit": { "name": "limit", "in": "query", "description": "Page size. Default 25, maximum 100 (larger values are clamped, not rejected).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "Offset": { "name": "offset", "in": "query", "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "headers": { "RateLimitLimit": { "description": "Requests permitted in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Unix timestamp at which the window resets.", "schema": { "type": "integer" } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request", "validation_failed", "missing_credentials", "invalid_credentials", "insufficient_scope", "forbidden", "not_found", "unknown_version", "version_retired", "rate_limited", "internal_error", "service_unavailable" ] }, "message": { "type": "string", "description": "Human-readable. May change at any time — branch on `code`, never on this." }, "details": { "description": "Optional machine-readable context." }, "request_id": { "type": "string", "format": "uuid", "description": "Quote this when reporting a problem; it appears in the audit log." } } } } }, "Pagination": { "type": "object", "required": [ "limit", "offset", "has_more" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": [ "integer", "null" ] }, "has_more": { "type": "boolean" } } }, "Customer": { "type": "object", "description": "People receiving care.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "number", "boolean", "null" ] }, "given_name": { "type": [ "string", "number", "boolean", "null" ] }, "family_name": { "type": [ "string", "number", "boolean", "null" ] }, "name_infix": { "type": [ "string", "number", "boolean", "null" ] }, "date_of_birth": { "type": [ "string", "number", "boolean", "null" ] }, "status": { "type": [ "string", "number", "boolean", "null" ] }, "preferred_language_code": { "type": [ "string", "number", "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CarePlan": { "type": "object", "description": "The agreed plan of care for a customer.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": [ "string", "number", "boolean", "null" ] }, "status": { "type": [ "string", "number", "boolean", "null" ] }, "start_date": { "type": [ "string", "null" ], "format": "date" }, "end_date": { "type": [ "string", "null" ], "format": "date" }, "next_review_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Appointment": { "type": "object", "description": "Scheduled care appointments.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "care_plan_id": { "type": [ "string", "null" ], "format": "uuid" }, "series_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": [ "string", "number", "boolean", "null" ] }, "scheduled_start": { "type": [ "string", "number", "boolean", "null" ] }, "scheduled_end": { "type": [ "string", "number", "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Visit": { "type": "object", "description": "Executed care visits.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "appointment_id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": [ "string", "number", "boolean", "null" ] }, "checked_in_at": { "type": [ "string", "null" ], "format": "date-time" }, "checked_out_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Invoice": { "type": "object", "description": "Issued and draft invoices.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "invoice_number": { "type": [ "string", "number", "boolean", "null" ] }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": [ "string", "number", "boolean", "null" ] }, "issue_date": { "type": [ "string", "null" ], "format": "date" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "total": { "type": [ "string", "number", "boolean", "null" ] }, "amount_paid": { "type": [ "string", "number", "boolean", "null" ] }, "outstanding_balance": { "type": [ "string", "number", "boolean", "null" ] }, "currency_code": { "type": [ "string", "number", "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Payment": { "type": "object", "description": "Payments recorded against invoices.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "amount": { "type": [ "string", "number", "boolean", "null" ] }, "currency_code": { "type": [ "string", "number", "boolean", "null" ] }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "method": { "type": [ "string", "number", "boolean", "null" ] }, "reference": { "type": [ "string", "number", "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Document": { "type": "object", "description": "Documents attached to a customer or care plan.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "customer_id": { "type": [ "string", "null" ], "format": "uuid" }, "care_plan_id": { "type": [ "string", "null" ], "format": "uuid" }, "category_id": { "type": [ "string", "null" ], "format": "uuid" }, "title": { "type": [ "string", "number", "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Notification": { "type": "object", "description": "Notifications raised by the platform.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "category": { "type": [ "string", "number", "boolean", "null" ] }, "title": { "type": [ "string", "number", "boolean", "null" ] }, "body": { "type": [ "string", "number", "boolean", "null" ] }, "related_entity_type": { "type": [ "string", "number", "boolean", "null" ] }, "related_entity_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ReportDefinition": { "type": "object", "description": "Reports available to run. Executing one is a separate call.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "number", "boolean", "null" ] }, "name": { "type": [ "string", "number", "boolean", "null" ] }, "description": { "type": [ "string", "number", "boolean", "null" ] }, "category": { "type": [ "string", "number", "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Workflow": { "type": "object", "description": "Automation workflows defined for the tenant.", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "code": { "type": [ "string", "number", "boolean", "null" ] }, "name": { "type": [ "string", "number", "boolean", "null" ] }, "description": { "type": [ "string", "number", "boolean", "null" ] }, "status": { "type": [ "string", "number", "boolean", "null" ] }, "category": { "type": [ "string", "number", "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }