Skip to main content

​
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 sequence keeps every spec decision documented, from project creation to final output, so product, design, and engineering stay aligned.
1

Create a new project

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 Prompt Project"}' \
     "https://sapi.withsutro.com/projects"
Response (HTTP 201)
{
  "id": "abc123",
  "name": "My Prompt Project",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
The project details are stored in project.json; refer to that file in upcoming steps.
2

Create an application

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 \
     "https://sapi.withsutro.com/projects/$(jq -r '.id' < project.json)/applications"
Response (HTTP 201)
{
  "id": "def456",
  "projectId": "abc123",
  "scode": {},
  "status": "Initialized",
  "createdAt": "2025-01-15T10:31:00.000Z",
  "updatedAt": "2025-01-15T10:31:00.000Z"
}
The application details are stored in application.json; refer to that file in upcoming steps.
3

Upload your prompt as an attachment

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 attachment.json \
     -d '{
       "type": "PROMPT",
       "prompt": "<YOUR_APP_PROMPT_HERE>"
     }' \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/attachments"
Replace <YOUR_APP_PROMPT_HERE> with the full text description of your app.Response (HTTP 201)
{
  "id": "attachment_id_12345xyz",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
The attachment details are stored in attachment.json; refer to that file in the next step.
4

Trigger spec generation

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 "{\"attachmentId\": \"$(jq -r '.id' < attachment.json)\"}" \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/spec"
Response (HTTP 200)
{
  "success": true
}
5

Monitor spec generation

This endpoint returns the overall application status, including frontend, backend, and spec generation jobs.
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
Spec generation is complete when the spec task shows Completed.
6

Retrieve the generated spec

After the spec job is completed, retrieve the generated spec:
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 GET \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/spec" | jq
Response (HTTP 200)
{
  "domainModel": { /* ... */ },
  "requirements": [ /* ... */ ],
  "sitemap": { /* ... */ }
}
Your prompt is now a structured spec. Share it with stakeholders or plug it into planning workflows without missing context.

​
Examples