Skip to main content

​
Overview

This guide shows you how to use the Sutro AI Assistant to make changes to your built application using natural language. The assistant allows you to have a conversation about your application and trigger modifications through simple prompts.

​
Before you begin

​
Roles & credentials

​
Prerequisites

  • You should have already created a project and deployed an application. If you haven’t, follow the Building full-stack apps guide first.
  • jq and curl

​
Variables and files

  • You’ll need the sutro.key and sutro.crt files created in Step 2 of the Builder authentication setup.
  • Use Step 4 to generate JWTs for your requests and store them in the BUILDER_JWT environment variable.
  • Download the Sutro Certificate Authority (CA) certificate from /certs/ca.crt to secure API requests.
  • Have your project.json file handy (or at least the project ID).

​
Steps

This flow keeps the entire conversation auditable—every message, change, and status update is captured so you can steer the assistant with confidence.
1

View conversation history

Before making changes, you may want to see the existing conversation history for your project. Messages are stored per project to maintain conversation context.Call GET /projects/{projectId}/messages.
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -s \
     -X GET \
     https://sapi.withsutro.com/projects/$(jq -r '.id' < project.json)/messages | jq
This will return a list of all messages (both user and assistant messages) for your project, allowing you to see the conversation history.
2

Send a message to the assistant

Send a message to the assistant to start or continue a conversation. When you send a message, it will:
  • Create a user message in the conversation history
  • Process your message with the AI assistant
  • Trigger changes to your application if your message requests modifications
  • Return the assistant’s response
The components that can be modified (frontend, backend, or both) are determined by your project’s components configuration set at project creation. This cannot be overridden.Call POST /projects/{projectId}/messages.
curl -H "Content-Type: application/json" \
     -H "Authorization: Bearer ${BUILDER_JWT}" \
     -H "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
     -cacert ca.crt \
     --key sutro.key \
     --cert sutro.crt \
     -X POST \
     -d '{
       "content": [
         {
           "type": "text",
           "text": "Add a dark mode toggle button in the header that switches between light and dark themes"
         }
       ]
     }' \
     https://sapi.withsutro.com/projects/$(jq -r '.id' < project.json)/messages
The response will include the assistant’s message, which may contain information about the changes being made or confirmation that the changes have been processed. The user message is automatically stored in the conversation history.
Conversation history and updates stay in sync. You’re now ready to guide the assistant through iterative refinements.

​
Tips

  • Be specific: When describing changes you want to make, be as specific as possible. For example, “Add a dark mode toggle button in the header” is better than “add dark mode”.
  • Iterate: You can have multiple conversations with the assistant. Each message builds on the conversation history, so you can refine your requests based on previous interactions.
  • Check your project components: Remember that the assistant can only modify components that were configured when you created your project. If you created a project with only backend, the assistant won’t be able to modify frontend components.
  • Monitor your application: After triggering changes, you may want to check your application status and redeploy if necessary to see the changes take effect.