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

Every action in this flow protects traceability, from project creation, to attachments, to final spec, so product and engineering stay aligned on what’s shipping.
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 Figma Project"}' \
     "https://sapi.withsutro.com/projects"
Response (HTTP 201)
{
  "id": "abc123",
  "name": "My Figma 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 Figma project 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": "FIGMA",
       "value": {
         "figmaUrl": "<FIGMA_URL>",
         "pat": "<FIGMA_PERSONAL_ACCESS_TOKEN>"
       }
     }' \
     "https://sapi.withsutro.com/applications/$(jq -r '.id' < application.json)/attachments"
Replace <FIGMA_URL> and <FIGMA_PERSONAL_ACCESS_TOKEN> with your Figma file link and your personal access token.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)
{
  "metadata": { /* ... */ },
  "summary": "...",
  "designSystem": { /* ... */ },
  "informationArchitecture": { /* ... */ },
  "userFlows": { /* ... */ },
  "notes": { /* ... */ }
}
Your Figma design now translates into a ready-to-share specification. Hand it to engineering or product and stay perfectly aligned.

​
Examples