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

​
Tools

  • jq and curl

​
Security bundle

Download security-bundle.zip from the Sutro Console during onboarding. Extract it and run all commands from that directory. The bundle includes your API client credentials (apiClient.id, mtls.key, mtls.crt), the Sutro CA certificate (ca.crt), and a pre-generated Builder JWT (builder.jwt) valid for 7 days.
The test bundle creates a test builder for quick API testing, not for production. See How to Secure Connections for production setup.

​
Prerequisites

  • You should have already created a project and deployed an application. If you haven’t, follow the Building full-stack apps guide first.
  • Have your project.json file handy (or at least the project ID).

​
Verify your connection

Test that your credentials work by calling the hello endpoint: 
curl -H "Authorization: Bearer $(cat builder.jwt)" \
     -H "x-sutro-api-client: $(cat apiClient.id)" \
     --cacert ca.crt \
     --key mtls.key \
     --cert mtls.crt \
     "https://sapi.withsutro.com/hello"
You should see a response confirming your API client, Builder, and organization.

​
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 $(cat builder.jwt)" \
     -H "x-sutro-api-client: $(cat apiClient.id)" \
     --cacert ca.crt \
     --key mtls.key \
     --cert mtls.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 $(cat builder.jwt)" \
     -H "x-sutro-api-client: $(cat apiClient.id)" \
     --cacert ca.crt \
     --key mtls.key \
     --cert mtls.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.