> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/api-reference/chat.md). # Chat ## Search: start pagination > Let assume that we have the following chat (messages in the list are sorted from older to newest):\ > \ > \* Hello0\ > \* Hello1\ > \* Test1\ > \* Test2\ > \* Hello2\ > \* Test3\ > \* Test4\ > \ > \ > So let’s search by query “Hello”. Assume pageSize=2 and contentPageSize=1 and make the following request\ > \ > 1\. HTTP Method: GET\ > 2\. HTTP URL: \` > \ > \ > As you can see, two messages are found: the first is “Hello2” and the second is “Hello1”. “content” length is limited to pageSize, so to fetch next messages that matches query you should use pass “meta.nextPageToken” as pageToken. ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Chat","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"PatientId":{"name":"patientId","in":"path","required":true,"description":"UUID of the patient record","schema":{"type":"string","format":"uuid"}}},"schemas":{"ChatSearchPage":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ChatMessagePageMeta"},"content":{"type":"array","items":{"$ref":"#/components/schemas/ChatSearchMessage"}}}},"ChatMessagePageMeta":{"allOf":[{"$ref":"#/components/schemas/ChatPageTokens"},{"type":"object","properties":{"isFound":{"type":"boolean"},"pageSize":{"type":"integer"}}}]},"ChatPageTokens":{"type":"object","properties":{"nextPageToken":{"type":"string","nullable":true},"prevPageToken":{"type":"string","nullable":true}}},"ChatSearchMessage":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ChatPageTokens"},"message":{"$ref":"#/components/schemas/ChatMessage"}}},"ChatMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"sender":{"$ref":"#/components/schemas/ChatUser","nullable":true,"readOnly":true},"receiver":{"$ref":"#/components/schemas/ChatUser","nullable":true,"readOnly":true},"message":{"type":"string","description":"Required if attachmentAsFiles is empty."},"externalId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/File"}},"skipEvent":{"type":"boolean"},"deletedAt":{"type":"string","format":"date-time","nullable":true,"readOnly":true}}},"ChatUser":{"type":"object","properties":{"clientType":{"$ref":"#/components/schemas/ClientType"},"id":{"type":"string","format":"uuid"},"titleName":{"type":"string","nullable":true},"patientFullName":{"type":"string","nullable":true}}},"ClientType":{"type":"string","enum":["CS_TOOL_CLIENT","USER","API_CLIENT","PATIENT","CONTACT","WEBHOOK","INTERNAL_SERVICE","ANONYMOUS"]},"File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"Bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients/{patientId}/chat/search":{"get":{"summary":"Search: start pagination","tags":["Chat"],"operationId":"Search_start_pagination","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/PatientId"},{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Query for search"},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","default":20},"description":"How many search results per page will returns"},{"name":"contentPageSize","in":"query","required":false,"schema":{"type":"string"},"description":"How many messages per page will return get messages api when you'll pass content.meta.nextPageToken or content.meta.prevPageToken as pageToken param to that api"},{"name":"includeArchived","in":"query","required":false,"schema":{"type":"boolean"},"description":"If true, include archived messages, otherwise not."},{"name":"pageToken","in":"query","required":false,"description":"Token for fetching next or previous search results. Mutually exclusive with query/pageSize/contentPageSize.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated chat search results (fresh page via `query`, or resume via `pageToken`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSearchPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Let assume that we have the following chat (messages in the list are sorted from older to newest):\n\n* Hello0\n* Hello1\n* Test1\n* Test2\n* Hello2\n* Test3\n* Test4\n \n\nSo let’s search by query “Hello”. Assume pageSize=2 and contentPageSize=1 and make the following request\n\n1. HTTP Method: GET\n2. HTTP URL: `https://api.live.welkincloud.io/gh/sb-demo/patient/7272b601-bb09-4abf-87c0-ade48ddfaea0/chat/search?query=hello&pageSize=2&contentPageSize=1&includeArchived=true`\n \n\nAs you can see, two messages are found: the first is “Hello2” and the second is “Hello1”. “content” length is limited to pageSize, so to fetch next messages that matches query you should use pass “meta.nextPageToken” as pageToken."}}}} ``` ## Chat: Send message from patient to care team > Send message from patient to care team.\ > \ > \`URL Structure: {{url}} / {{tenantName}} / {{instanceName}} / patients / {{patientId}} / chat / inbound\`\ > \ > in our example it would be:\ > \ > \` > \ > Supported file extensions: jpg,mp3,pdf,png,jpeg,wav,ogg ```json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Chat","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"PatientId":{"name":"patientId","in":"path","required":true,"description":"UUID of the patient record","schema":{"type":"string","format":"uuid"}}},"schemas":{"ChatMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"sender":{"$ref":"#/components/schemas/ChatUser","nullable":true,"readOnly":true},"receiver":{"$ref":"#/components/schemas/ChatUser","nullable":true,"readOnly":true},"message":{"type":"string","description":"Required if attachmentAsFiles is empty."},"externalId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/File"}},"skipEvent":{"type":"boolean"},"deletedAt":{"type":"string","format":"date-time","nullable":true,"readOnly":true}}},"ChatUser":{"type":"object","properties":{"clientType":{"$ref":"#/components/schemas/ClientType"},"id":{"type":"string","format":"uuid"},"titleName":{"type":"string","nullable":true},"patientFullName":{"type":"string","nullable":true}}},"ClientType":{"type":"string","enum":["CS_TOOL_CLIENT","USER","API_CLIENT","PATIENT","CONTACT","WEBHOOK","INTERNAL_SERVICE","ANONYMOUS"]},"File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"Bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}},"ChatInboundRequest":{"type":"object","description":"Either `message` or an attached file is required.","properties":{"message":{"type":"string"},"attachmentAsFiles":{"type":"array","items":{"type":"string","format":"binary"},"description":"Supported extensions: jpg, mp3, pdf, png, jpeg, wav, ogg."}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients/{patientId}/chat/inbound":{"post":{"summary":"Chat: Send message from patient to care team","tags":["Chat"],"operationId":"Chat_Send_message_from_patient_to_care_team","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/PatientId"}],"responses":{"201":{"description":"Message sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatMessage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Send message from patient to care team.\n\n`URL Structure: {{url}} / {{tenantName}} / {{instanceName}} / patients / {{patientId}} / chat / inbound`\n\nin our example it would be:\n\n`https://api.live.welkincloud.io/gh/sb-demo/patients/7272b601-bb09-4abf-87c0-ade48ddfaea0/chat/inbound`\n\nSupported file extensions: jpg,mp3,pdf,png,jpeg,wav,ogg","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatInboundRequest"}},"multipart/form-data":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Required if attachmentAsFiles is empty."},"attachmentAsFiles":{"type":"array","items":{"type":"string","format":"binary"},"description":"Supported extensions: jpg, mp3, pdf, png, jpeg, wav, ogg."}}}}}}}}}} ``` ## Get Messages > Endpoint: GET {{url}}/{{tenantName}}/{{instanceName}}/patients/{{patientId}}/chat\ > \ > Description: \ > This endpoint retrieves the chat history for a specific patient. It allows you to view the conversation or messages exchanged between the patient and the healthcare provider or system.\ > \ > URL Parameters:\ > \ > \- {{url}}: The base URL of the API.\ > \- {{tenantName}}: The name or identifier of the tenant within the system.\ > \- {{instanceName}}: The name or identifier of the specific instance within the tenant.\ > \- {{patientId}}: The unique identifier of the patient for whom the chat history is being requested.\ > \ > \ > HTTP Method: \ > GET\ > \ > Authorization: \ > This endpoint may require authentication and authorization based on the system's security policies. Valid credentials or access tokens may be required to access the chat history.\ > \ > Response: \ > The response from this endpoint will typically be in JSON format and will contain the chat history for the specified patient. The exact structure of the response may vary based on the system's implementation. It may include details such as timestamps, sender information, and message content.\ > \ > Example Request: \ > GET {{url}}/{{tenantName}}/{{instanceName}}/patients/123456/chat\ > \ > Example Response:\ > \ > \`\`\`\ > jsonCopy code{\ > "patientId": "123456",\ > "chatHistory": \[\ > {\ > "timestamp": "2023-06-08T10:30:00Z",\ > "sender": "Healthcare Provider",\ > "message": "Hello, how can I assist you today?"\ > },\ > {\ > "timestamp": "2023-06-08T10:32:00Z",\ > "sender": "Patient",\ > "message": "I'm experiencing some chest pain."\ > },\ > {\ > "timestamp": "2023-06-08T10:35:00Z",\ > "sender": "Healthcare Provider",\ > "message": "I recommend scheduling an appointment for further evaluation. Can you come in tomorrow?"\ > },\ > {\ > "timestamp": "2023-06-08T10:37:00Z",\ > "sender": "Patient",\ > "message": "Yes, tomorrow works for me. What time?"\ > }\ > ]\ > }\ > \ > \`\`\`\ > \ > Note: The above example response is for illustrative purposes only and may not reflect the actual response format of the system.\ > \ > Error Handling: \ > In case of errors, the endpoint may return appropriate HTTP status codes along with error messages or error objects to indicate the failure reason. Common status codes include 4xx for client errors (e.g., invalid parameters) and 5xx for server errors (e.g., internal server error).\ > \ > Security Considerations: \ > To ensure the privacy and security of patient information, proper authentication and authorization mechanisms should be implemented for accessing this endpoint. Access to patient chat history should be restricted to authorized personnel only.\ > \ > Rate Limiting: \ > To prevent abuse or overload on the system, rate limiting mechanisms may be applied to this endpoint. Clients may need to adhere to certain limits on the number of requests per time period.\ > \ > Note: Replace the placeholder variables (e.g., {{url}}, {{tenantName}}, {{instanceName}}, {{patientId}}) with actual values specific to your system implementation.\ > \ > Note: Received links to attachements expires in 5 minutes. You can refresh them by the endpoint ' Get File by fileId'. ````json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Chat","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"PatientId":{"name":"patientId","in":"path","required":true,"description":"UUID of the patient record","schema":{"type":"string","format":"uuid"}}},"schemas":{"ChatMessagePage":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ChatMessagePageMeta"},"content":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}}},"ChatMessagePageMeta":{"allOf":[{"$ref":"#/components/schemas/ChatPageTokens"},{"type":"object","properties":{"isFound":{"type":"boolean"},"pageSize":{"type":"integer"}}}]},"ChatPageTokens":{"type":"object","properties":{"nextPageToken":{"type":"string","nullable":true},"prevPageToken":{"type":"string","nullable":true}}},"ChatMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"sender":{"$ref":"#/components/schemas/ChatUser","nullable":true,"readOnly":true},"receiver":{"$ref":"#/components/schemas/ChatUser","nullable":true,"readOnly":true},"message":{"type":"string","description":"Required if attachmentAsFiles is empty."},"externalId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/File"}},"skipEvent":{"type":"boolean"},"deletedAt":{"type":"string","format":"date-time","nullable":true,"readOnly":true}}},"ChatUser":{"type":"object","properties":{"clientType":{"$ref":"#/components/schemas/ClientType"},"id":{"type":"string","format":"uuid"},"titleName":{"type":"string","nullable":true},"patientFullName":{"type":"string","nullable":true}}},"ClientType":{"type":"string","enum":["CS_TOOL_CLIENT","USER","API_CLIENT","PATIENT","CONTACT","WEBHOOK","INTERNAL_SERVICE","ANONYMOUS"]},"File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"Bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/patients/{patientId}/chat":{"get":{"summary":"Get Messages","tags":["Chat"],"operationId":"Get_Messages","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/PatientId"},{"name":"pageToken","in":"query","required":false,"description":"Token for fetching a specific page. Mutually exclusive with pageSize.","schema":{"type":"string"}},{"name":"includeArchived","in":"query","required":false,"description":"If true, include archived messages in the result.","schema":{"type":"boolean"}},{"name":"size","in":"query","required":false,"description":"Page size. Mutually exclusive with pageToken.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated chat messages (fresh page, or resume via `pageToken`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatMessagePage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Endpoint: GET {{url}}/{{tenantName}}/{{instanceName}}/patients/{{patientId}}/chat\n\nDescription: \nThis endpoint retrieves the chat history for a specific patient. It allows you to view the conversation or messages exchanged between the patient and the healthcare provider or system.\n\nURL Parameters:\n\n- {{url}}: The base URL of the API.\n- {{tenantName}}: The name or identifier of the tenant within the system.\n- {{instanceName}}: The name or identifier of the specific instance within the tenant.\n- {{patientId}}: The unique identifier of the patient for whom the chat history is being requested.\n \n\nHTTP Method: \nGET\n\nAuthorization: \nThis endpoint may require authentication and authorization based on the system's security policies. Valid credentials or access tokens may be required to access the chat history.\n\nResponse: \nThe response from this endpoint will typically be in JSON format and will contain the chat history for the specified patient. The exact structure of the response may vary based on the system's implementation. It may include details such as timestamps, sender information, and message content.\n\nExample Request: \nGET {{url}}/{{tenantName}}/{{instanceName}}/patients/123456/chat\n\nExample Response:\n\n```\njsonCopy code{\n \"patientId\": \"123456\",\n \"chatHistory\": [\n {\n \"timestamp\": \"2023-06-08T10:30:00Z\",\n \"sender\": \"Healthcare Provider\",\n \"message\": \"Hello, how can I assist you today?\"\n },\n {\n \"timestamp\": \"2023-06-08T10:32:00Z\",\n \"sender\": \"Patient\",\n \"message\": \"I'm experiencing some chest pain.\"\n },\n {\n \"timestamp\": \"2023-06-08T10:35:00Z\",\n \"sender\": \"Healthcare Provider\",\n \"message\": \"I recommend scheduling an appointment for further evaluation. Can you come in tomorrow?\"\n },\n {\n \"timestamp\": \"2023-06-08T10:37:00Z\",\n \"sender\": \"Patient\",\n \"message\": \"Yes, tomorrow works for me. What time?\"\n }\n ]\n}\n\n```\n\nNote: The above example response is for illustrative purposes only and may not reflect the actual response format of the system.\n\nError Handling: \nIn case of errors, the endpoint may return appropriate HTTP status codes along with error messages or error objects to indicate the failure reason. Common status codes include 4xx for client errors (e.g., invalid parameters) and 5xx for server errors (e.g., internal server error).\n\nSecurity Considerations: \nTo ensure the privacy and security of patient information, proper authentication and authorization mechanisms should be implemented for accessing this endpoint. Access to patient chat history should be restricted to authorized personnel only.\n\nRate Limiting: \nTo prevent abuse or overload on the system, rate limiting mechanisms may be applied to this endpoint. Clients may need to adhere to certain limits on the number of requests per time period.\n\nNote: Replace the placeholder variables (e.g., {{url}}, {{tenantName}}, {{instanceName}}, {{patientId}}) with actual values specific to your system implementation.\n\nNote: Received links to attachements expires in 5 minutes. You can refresh them by the endpoint ' Get File by fileId'."}}}} ```` ## Get File by fileId > Endpoint: GET {{url}}/{{tenantName}}/{{instanceName}}/files/:fileId\ > \ > Description: \ > A file refresh endpoint is required to renew an expired link to a file. The endpoint should accept a fileID as a parameter in order to proceed.\ > \ > URL Parameters:\ > \ > \- {{url}}: The base URL of the API.\ > \- {{tenantName}}: The name or identifier of the tenant within the system.\ > \- {{instanceName}}: The name or identifier of the specific instance within the tenant.\ > \- :fileId: The unique identifier of the file being requested. This parameter should be replaced with the actual fileId value.\ > \ > \ > HTTP Method: \ > GET\ > \ > Authorization: \ > Depending on the system's security policies, this endpoint may require authentication and authorization. Valid credentials or access tokens may be required to access and download the file.\ > \ > Response: \ > The response from this endpoint will typically contain the requested file or the necessary information to retrieve the file. The exact structure of the response may depend on the system's implementation. If the file is available, the response may include the file content or a link to download the file.\ > \ > Example Request: \ > GET {{url}}/{{tenantName}}/{{instanceName}}/files/123456\ > \ > Example Response (File Content): \ > The response can vary based on the file type and system implementation. For binary files, the response might include the file content as raw bytes.\ > \ > Example Response (File Download Link):\ > \ > \`\`\`\ > jsonCopy code{\ > "fileId": "123456",\ > "fileName": "example.pdf",\ > "downloadLink": " > }\ > \ > \`\`\`\ > \ > Note: The above example response is for illustrative purposes only and may not reflect the actual response format of the system.\ > \ > Error Handling: \ > In case of errors, the endpoint may return appropriate HTTP status codes along with error messages or error objects to indicate the failure reason. Common status codes include 4xx for client errors (e.g., invalid fileId) and 5xx for server errors (e.g., internal server error).\ > \ > Security Considerations: \ > To ensure the security and privacy of files, proper authentication and authorization mechanisms should be implemented for accessing this endpoint. Access to files may need to be restricted based on user roles and permissions.\ > \ > Rate Limiting: \ > To prevent abuse or overload on the system, rate limiting mechanisms may be applied to this endpoint. Clients may need to adhere to certain limits on the number of requests per time period.\ > \ > Note: Replace the placeholder variables (e.g., {{url}}, {{tenantName}}, {{instanceName}}, :fileId) with actual values specific to your system implementation. ````json {"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Chat","description":""}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FileId":{"name":"fileId","in":"path","required":true,"description":"UUID of the uploaded file","schema":{"type":"string","format":"uuid"}}},"schemas":{"SignedFile":{"allOf":[{"$ref":"#/components/schemas/File"},{"type":"object","properties":{"url":{"type":"string","format":"uri"},"thumbnailUrl":{"type":"string","format":"uri","nullable":true}}}]},"File":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"Bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/files/{fileId}":{"get":{"summary":"Get File by fileId","tags":["Chat"],"operationId":"Get_File_by_fileId","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FileId"}],"responses":{"200":{"description":"File metadata with a signed, time-limited download URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedFile"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Endpoint: GET {{url}}/{{tenantName}}/{{instanceName}}/files/:fileId\n\nDescription: \nA file refresh endpoint is required to renew an expired link to a file. The endpoint should accept a fileID as a parameter in order to proceed.\n\nURL Parameters:\n\n- {{url}}: The base URL of the API.\n- {{tenantName}}: The name or identifier of the tenant within the system.\n- {{instanceName}}: The name or identifier of the specific instance within the tenant.\n- :fileId: The unique identifier of the file being requested. This parameter should be replaced with the actual fileId value.\n \n\nHTTP Method: \nGET\n\nAuthorization: \nDepending on the system's security policies, this endpoint may require authentication and authorization. Valid credentials or access tokens may be required to access and download the file.\n\nResponse: \nThe response from this endpoint will typically contain the requested file or the necessary information to retrieve the file. The exact structure of the response may depend on the system's implementation. If the file is available, the response may include the file content or a link to download the file.\n\nExample Request: \nGET {{url}}/{{tenantName}}/{{instanceName}}/files/123456\n\nExample Response (File Content): \nThe response can vary based on the file type and system implementation. For binary files, the response might include the file content as raw bytes.\n\nExample Response (File Download Link):\n\n```\njsonCopy code{\n \"fileId\": \"123456\",\n \"fileName\": \"example.pdf\",\n \"downloadLink\": \"https://example.com/downloads/123456\"\n}\n\n```\n\nNote: The above example response is for illustrative purposes only and may not reflect the actual response format of the system.\n\nError Handling: \nIn case of errors, the endpoint may return appropriate HTTP status codes along with error messages or error objects to indicate the failure reason. Common status codes include 4xx for client errors (e.g., invalid fileId) and 5xx for server errors (e.g., internal server error).\n\nSecurity Considerations: \nTo ensure the security and privacy of files, proper authentication and authorization mechanisms should be implemented for accessing this endpoint. Access to files may need to be restricted based on user roles and permissions.\n\nRate Limiting: \nTo prevent abuse or overload on the system, rate limiting mechanisms may be applied to this endpoint. Clients may need to adhere to certain limits on the number of requests per time period.\n\nNote: Replace the placeholder variables (e.g., {{url}}, {{tenantName}}, {{instanceName}}, :fileId) with actual values specific to your system implementation."}}}} ```` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.welkinhealth.com/api-reference/chat.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.