Skip to main content

​
Steps

This sequence keeps every spec decision documented—from authentication to final output—so product, design, and engineering stay aligned.
1

Authenticate

Before making API calls, create a JWT token for secure authentication.If your setup supports single-command generation:
jwt encode --secret @jwt.pem \
           -A RS256 \
           --iss 'https://auth.example.com' \
           --sub "$BUILDER_ID" \
           --aud "https://sapi.withsutro.com" \
           --exp=$(($(date +%s) + 3600))
Otherwise, follow Securing Connections to create both a JWT token and mTLS certificate.
2

Create a new project

curl --request POST \
  --url "https://sapi.withsutro.com/projects" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <jwt-token>" \
  --header "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --data '{
    "name": "My Prompt Project"
  }'
Response (HTTP 201)
{
  "id": "abc123",
  "name": "My Figma Project",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}
Save the project ID — it’s used in later steps.
3

Create an application

curl --request POST \
  --url "https://sapi.withsutro.com/projects/<PROJECT_ID>/applications" \
  --header "Content-Type: application/json" \
  --header "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --header "Authorization: Bearer <jwt-token>"
Replace <PROJECT_ID> with the ID from the previous step.Response (HTTP 201)
{
  "id": "def456",
  "projectId": "abc123",
  "scode": {},
  "status": "Initialized",
  "createdAt": "2025-01-15T10:31:00.000Z",
  "updatedAt": "2025-01-15T10:31:00.000Z"
}
Save the application ID — it’s used in later steps.
4

Upload your prompt as an attachment

curl --request POST \
  --url "https://sapi.withsutro.com/applications/<APPLICATION_ID>/attachments" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <jwt-token>" \
  --header "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --data '{
    "type": "APP_PROMPT",
    "value": "<YOUR_APP_PROMPT_HERE>"
  }'
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"
}
Save the attachment ID — it’s used in later steps.
5

Trigger spec generation

curl --request POST \
  --url "https://sapi.withsutro.com/applications/<APPLICATION_ID>/spec" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <jwt-token>" \
  --header "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --data '{
    "attachmentId": "<YOUR_ATTACHMENT_ID>"
  }'
Replace <YOUR_ATTACHMENT_ID> with the ID returned in the previous step.Response (HTTP 200)
{
  "success": true
}
6

Monitor spec generation

This endpoint returns the overall application status, including frontend, backend, and spec generation jobs.
curl --request GET \
  --url "https://sapi.withsutro.com/applications/<APPLICATION_ID>/status" \
  --header "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --header "Authorization: Bearer <jwt-token>"
Spec generation is complete when the spec task shows Completed.
7

Retrieve the generated spec

After the spec job is completed, retrieve the generated spec:
curl --request GET \
  --url "https://sapi.withsutro.com/applications/<APPLICATION_ID>/spec" \
  --header "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --header "Authorization: Bearer <jwt-token>"
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