Add method for creating a suggestion

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Version 0.4.11 - 2026-01-15
+
+- Add create_suggestion method
+
 ## Version 0.4.10 - 2025-11-24
 
 - Add get_agent_statistics method

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cradl"
-version = "0.4.10"
+version = "0.4.11"
 description = "Python SDK for Cradl"
 authors = [{ name = "Cradl", email = "hello@cradl.ai" }]
 readme = "README.md"

src/cradl/client.py

@@ -3393,3 +3393,26 @@ def create_action_run(
         })
         return self._make_request(requests.post, f'/actions/{action_id}/runs', body=body)
 
+    def create_suggestion(self, text: str, document_id: str, suggestion_type: str ='raw', **optional_args) -> Dict:
+        """Creates a suggestion, calls the POST /suggestions endpoint.
+
+        :param text: text to use as a prompt for the agent
+        :type text: str
+        :param document_id: Id of the document
+        :type document_id: str
+        :param suggestion_type: what kind of suggestion to get
+        :type suggestion_type: str
+        :return: Suggestion response from REST API
+        :rtype: dict
+
+        :raises: :py:class:`~cradl.InvalidCredentialsException`, :py:class:`~cradl.TooManyRequestsException`,\
+ :py:class:`~cradl.LimitExceededException`, :py:class:`requests.exception.RequestException`
+        """
+        body = {
+            'text': text,
+            'documentId': document_id,
+            'type': suggestion_type,
+            **optional_args,
+        }
+        return self._make_request(requests.post, '/suggestions', body=body)
+

tests/test_suggestions.py

@@ -0,0 +1,15 @@
+import logging
+import random
+from pathlib import Path
+
+import pytest
+from cradl.client import Client
+
+from . import service
+
+
+def test_create_suggestion(client: Client):
+    text = 'foobar'
+    document_id = service.create_document_id()
+    response = client.create_suggestion(text, document_id, 'raw')
+    assert 'suggestion' in response, 'Missing suggestion in response'