Skip to main content

​
Overview

This tutorial walks through the steps of generating a simple API server from scratch using the Sutro API.

​
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

This flow takes you from prompt to deployment so every asset (project, app, and OpenAPI spec) stays under your control the whole time.
1

Create a Project

Start by creating a Project to hold the prompt, application, and generated assets.Add a short description so you remember the goal. In this example, use “My To Do Server”.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 To Do Server"
     }' \
     "https://sapi.withsutro.com/projects"
Since we’re only building a backend API, we omit the components array, which defaults to ["backend"]. To include a frontend, pass "components": ["backend", "frontend"]. See the full-stack quickstart for details.
Congratulations! You’ve just created a Sutro Project.The project details now live in project.json; refer to that file in upcoming steps.
2

Create an Application

Next, create an Application. Most Projects contain a single Application.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; two more steps and it will be building…
3

Add a Prompt to the Application

Provide the Application with a prompt so the LLM knows what to generate.Since this tutorial builds a to-do server, use the following prompt:

Build me an API server that helps users track To Dos. It should include the ability to set deadlines on To Do items, as well as mark them completed
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":"Build me an API server that helps users track To Dos.\n\nIt should include the ability to set deadlines on To Do items, as well as mark them completed"}' \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/attachments"
The prompt is now attached; the Application is ready to generate.
4

Generate the Application

Generating an API server takes a little time, so call the Sutro API to start the process. Monitoring happens in the next step.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 will return quickly; our API server is being generated.
5

Monitor for generation to complete

Because curl drives this tutorial, poll the API for the Application’s status.The -s flag limits output to just the Application status, so keep an eye out for unexpected text that might 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.
6

Deploy the Application

The application is ready to deploy.Just like generation, deployment takes time, so this API call starts a deployment and creates a new version.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 will contain the deploymentId of the deployment (so that we can its status) and the version that was generated.
7

Monitor for the deployment to complete

Monitor deployment the same way as 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)/version/$(jq -r '.version' < deployment.json)/deployment/$(jq -r '.deploymentId' < deployment.json)" | jq
Once the response says "Successful", the API is ready to use.
8

Start using the API

There are many ways to exercise the new API. Start by getting a description so you know the available paths and methods.Call GET /applications/{applicationId}/versions/{version}/openapi.
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 openapi.yml \
     -X GET \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/version/$(jq -r '.version' < deployment.json)/openapi"
With the OpenAPI document in hand, pick your favorite API client and start exploring.This API doesn’t have any user credentials because security wasn’t configured. That’s fine for exploration, but add proper authentication before going live with real users’ data.
Your backend is generated, deployed, and documented. Grab the OpenAPI file and start wiring clients with confidence.

​
Reference