Skip to main content

​
Overview

This guide walks through the full workflow, from authentication to deployment, using the Sutro API to build a full-stack application from a prompt.
This guide will work for any of Sutro’s APIs.

​
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.

​
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

Sutro takes you through every stage, from prompts to production, so you retain end-to-end visibility while Sutro does the heavy lifting.
1

Create a new project

The first step is to create a new project. A project is like the container for your application, and it can have multiple components:
  • backend: A backend API hosted by Sutro
  • frontend: An optional frontend web application, hosted by Sutro, or exported as static bundle
The components array controls what gets generated. If omitted, only ["backend"] is created by default. Since we’re building a full-stack app, we explicitly request both backend and frontend.It’s currently not possible to create a standalone frontend project.Call POST /projects
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 \
     -o project.json \
     -d '{
       "name": "My New Project",
       "components": ["backend", "frontend"]
     }' \
     "https://sapi.withsutro.com/projects"
Congratulations! You’ve just created your first Sutro Project.The project details are stored in project.json; refer to that file in upcoming steps.
2

Create an app

Next, create an empty application within your project. This application will serve as the container for your generated code.Call POST /projects/{projectId}/applications
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 \
     -o application.json \
     -d '{
       "scode": {}
     }' \
     "https://sapi.withsutro.com/projects/$(jq -r '.id' < project.json)/applications"
Now you have an Application; next attach a prompt to it.
3

Attach a prompt

Attach a prompt to the application that describes what you want to build. This prompt will be used during the generation process.Call POST /applications/{applicationId}/attachments.
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 '{
       "type": "PROMPT",
       "prompt": "A todo app where users can create, edit, and delete tasks. Users should be able to mark tasks as complete and filter by status."
     }' \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/attachments"
The prompt is attached and the Application is ready to generate.
4

Generate the app

Generating an application takes a little time, so call the Sutro API to start the process and monitor it in the next step.This will automatically use the prompt that was attached to this specific application. Because you selected the backend and frontend components when creating the project, this will first generate a backend API, and then a frontend web application based on the prompt you attached.Call POST /applications/{applicationId}/generate.
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 \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/generate"
This call returns quickly; your application is being generated.
5

Monitor for generation to complete

Because curl drives this guide, poll the API for the application’s status.The -s flag limits output to the Application status, so unexpected text may signal local network issues.Call GET /applications/{applicationId}/status.
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/applications/$(jq -r '.id' < application.json)/status" | jq
Make this call every ~10 seconds until the status shows completion.Once the status shows "active", your application has been successfully generated and is ready to be published.
6

Publish the application

Now that your application has been generated, you need to publish it to make it accessible. Publishing creates a new version of your application and deploys it.Just like Application generation, Application deployment takes a little time, so this API call will start a deployment.It will also create a new Version of your Application.Call POST /applications/{applicationId}/deployment
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 \
     -o deployment.json \
     -X POST \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/deployment"
The deployment.json file contains the deploymentId of the deployment (so that we can check its status) and the versionId that was generated.
7

Monitor for the deployment to complete

Monitor deployment the same way you monitored generation.Call GET /applications/{applicationId}/versions/{version}/deployment/{deploymentId}
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/applications/$(jq -r '.id' < application.json)/versions/$(jq -r '.versionId' < deployment.json)/deployment/$(jq -r '.deploymentId' < deployment.json)" | jq
Once the response says that the status is "Successful", your application has been deployed and is ready to use.
8

Access your deployed application

Now that your application has been deployed, you can get the URL where it’s accessible.Call GET /applications/{applicationId} to retrieve the application details, including the public URL.
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/applications/$(jq -r '.id' < application.json)" | jq
The response includes the application details, including the URL where your frontend application is accessible. You can now open this URL in your browser to view and interact with your deployed full-stack application.
Your application is deployed, versioned, and ready for teammates or customers to explore. Share the URL with confidence!

​
Self-hosting the frontend

Instead of using Sutro’s hosted frontend, you can export a static bundle and serve it from your own infrastructure. This gives you complete control over hosting, CDN configuration, and deployment pipelines.
1

Configure CORS on your backend

When self-hosting the frontend, your frontend will make requests to the Sutro-hosted backend from a different origin. You need to configure CORS to allow these requests.Call PATCH /applications/{applicationId}/cors
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 PATCH \
     -d '{
       "allowedOrigins": ["http://localhost:8080"]
     }' \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/cors"
For production, replace http://localhost:8080 with your actual domain (e.g., https://app.yourdomain.com). You can include multiple origins in the array.
You can verify the current CORS configuration by calling GET /applications/{applicationId}/cors.
2

Export the frontend bundle

Download the production-ready frontend as a static bundle (HTML, CSS, JavaScript, and assets).Call GET /applications/{applicationId}/frontendBundle
curl -H "Authorization: Bearer $(cat builder.jwt)" \
     -H "x-sutro-api-client: $(cat apiClient.id)" \
     --cacert ca.crt \
     --key mtls.key \
     --cert mtls.crt \
     --output frontend-bundle.zip \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/frontendBundle"
The downloaded zip contains everything needed to serve your frontend from any static file server.
3

Extract and serve locally

Extract the bundle and serve it with any static file server. Here’s how to test locally using http-server:
# Extract the bundle
unzip frontend-bundle.zip -d frontend

# Install http-server if you don't have it
npm install -g http-server

# Serve the frontend on port 8080
http-server frontend -p 8080
Open http://localhost:8080 in your browser to see your application running locally against the Sutro-hosted backend.
Make sure the port matches the origin you configured in the CORS settings. If you’re using a different port, update the CORS configuration accordingly.

​
Reference