Skip to main content

​
Steps

Every action in this flow protects traceability—from auth, to attachments, to final spec—so product and engineering stay aligned on what’s shipping.
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 Figma 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 Figma project as an attachment

curl --request POST \
  --url "https://sapi.withsutro.com/applications/<APPLICATION_ID>/attachments" \
  --header "Content-Type: application/json" \
  --header "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --header "Authorization: Bearer <jwt-token>" \
  --data '{
    "type": "FIGMA",
    "value": {
      "figmaUrl": "<FIGMA_URL>",
      "pat": "<FIGMA_PERSONAL_ACCESS_TOKEN>"
    }
  }'
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"
}
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 "x-sutro-api-client: ${API_CLIENT_IDENTIFIER}" \
  --header "Authorization: Bearer <jwt-token>" \
  --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)
{
  "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