Skip to main content

API Quickstart

Automate backend generation using the Builder Backend API. Perfect for CI/CD, templates, or scripting.

Step 1: Get Your API Token​

Via Dashboard:​

  1. Log in to https://app.builder.dumbpotato.com
  2. Click your email (top right) → Account
  3. Go to API Tokens tab
  4. Click Create Token
    • Name: "My Script"
    • Scopes: read, write, generate
    • Expires: 30 days (or custom)
  5. Copy the token (shown once!)

Via API (sign in first):​

# Sign up
curl -X POST https://api.builder.dumbpotato.com/account/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-secure-password"}'

# Get access token
TOKEN=$(curl -X POST https://api.builder.dumbpotato.com/account/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-secure-password"}' \
  | jq -r '.access_token')

# Create API token
curl -X POST https://api.builder.dumbpotato.com/account/tokens \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CLI", "scopes": ["read", "write", "generate"], "expires_in_days": 30}' \
  | jq -r '.token'

Save this token: export BB_TOKEN=bb_pat_xxxxxxxxxxxx

Step 2: Create a Project​

curl -X POST https://api.builder.dumbpotato.com/projects \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Blog API"}' \
  | jq '.'

Save the project ID: export PROJECT_ID=<id from response>

Step 3: Add Entities​

Create "Post" entity:​

curl -X POST https://api.builder.dumbpotato.com/projects/$PROJECT_ID/entities \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Post",
    "fields": [
      {"name": "title", "type": "string", "required": true, "max_length": 200},
      {"name": "content", "type": "text", "required": true},
      {"name": "published", "type": "boolean", "default_value": "false"},
      {"name": "views", "type": "integer", "default_value": "0"}
    ]
  }' | jq '.'

Save the entity ID: export POST_ID=<id>

Create "Comment" entity:​

curl -X POST https://api.builder.dumbpotato.com/projects/$PROJECT_ID/entities \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Comment",
    "fields": [
      {"name": "body", "type": "text", "required": true},
      {"name": "author_name", "type": "string", "required": true, "max_length": 100}
    ]
  }' | jq '.'

Save: export COMMENT_ID=<id>

Step 4: Add Relation​

curl -X POST https://api.builder.dumbpotato.com/projects/$PROJECT_ID/relations \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_entity_id": "'$COMMENT_ID'",
    "to_entity_id": "'$POST_ID'",
    "type": "many_to_one",
    "name": "post"
  }' | jq '.'

Step 5: Validate​

curl -X POST https://api.builder.dumbpotato.com/projects/$PROJECT_ID/validate \
  -H "Authorization: Bearer $BB_TOKEN" \
  | jq '.'

Response: {"valid": true, "issues": []}

If issues exist, fix them before generating.

Step 6: Generate & Download​

Preview first (optional):​

curl -X POST https://api.builder.dumbpotato.com/projects/$PROJECT_ID/generate/preview \
  -H "Authorization: Bearer $BB_TOKEN" \
  | jq '.files | keys'

Download:​

curl -X GET https://api.builder.dumbpotato.com/projects/$PROJECT_ID/generate/download \
  -H "Authorization: Bearer $BB_TOKEN" \
  -o blog-api.zip

unzip blog-api.zip
cd blog-api
docker compose up --build

Step 7: Test Generated API​

# Create post
curl -X POST https://api.builder.dumbpotato.com/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "First Post", "content": "Hello from API!", "published": true}' \
  | jq '.'

# List posts
curl https://api.builder.dumbpotato.com/posts | jq '.'

# Create comment (use post ID from above)
curl -X POST https://api.builder.dumbpotato.com/comments \
  -H "Content-Type: application/json" \
  -d '{"body": "Great post!", "author_name": "Alice", "post_id": "<POST_ID>"}' \
  | jq '.'

Complete Script Example​

Save as create-blog.sh:

#!/bin/bash
set -e

BB_TOKEN=${BB_TOKEN:?'Set BB_TOKEN environment variable'}
API_URL=${API_URL:-https://api.builder.dumbpotato.com}

# Create project
echo "Creating project..."
PROJECT=$(curl -s -X POST $API_URL/projects \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Blog API"}')
PROJECT_ID=$(echo $PROJECT | jq -r '.id')
echo "Project ID: $PROJECT_ID"

# Create Post entity
echo "Creating Post entity..."
POST=$(curl -s -X POST $API_URL/projects/$PROJECT_ID/entities \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Post",
    "fields": [
      {"name": "title", "type": "string", "required": true, "max_length": 200},
      {"name": "content", "type": "text", "required": true},
      {"name": "published", "type": "boolean", "default_value": "false"}
    ]
  }')
POST_ID=$(echo $POST | jq -r '.id')

# Create Comment entity
echo "Creating Comment entity..."
COMMENT=$(curl -s -X POST $API_URL/projects/$PROJECT_ID/entities \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Comment",
    "fields": [
      {"name": "body", "type": "text", "required": true},
      {"name": "author_name", "type": "string", "required": true, "max_length": 100}
    ]
  }')
COMMENT_ID=$(echo $COMMENT | jq -r '.id')

# Create relation
echo "Creating relation..."
curl -s -X POST $API_URL/projects/$PROJECT_ID/relations \
  -H "Authorization: Bearer $BB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_entity_id": "'$COMMENT_ID'",
    "to_entity_id": "'$POST_ID'",
    "type": "many_to_one",
    "name": "post"
  }' > /dev/null

# Validate
echo "Validating..."
VALIDATION=$(curl -s -X POST $API_URL/projects/$PROJECT_ID/validate \
  -H "Authorization: Bearer $BB_TOKEN")

if [ "$(echo $VALIDATION | jq -r '.valid')" != "true" ]; then
  echo "Validation failed:"
  echo $VALIDATION | jq '.issues'
  exit 1
fi

# Download
echo "Downloading..."
curl -s -X GET $API_URL/projects/$PROJECT_ID/generate/download \
  -H "Authorization: Bearer $BB_TOKEN" \
  -o blog-api.zip

echo "Done! Run: unzip blog-api.zip && cd blog-api && docker compose up"

Usage:

chmod +x create-blog.sh
BB_TOKEN=bb_pat_your_token ./create-blog.sh

API Reference​

See Complete API Reference for all endpoints.

Key endpoints:

  • POST /projects - Create project
  • GET /projects - List your projects
  • POST /projects/{id}/entities - Add entity
  • POST /projects/{id}/relations - Add relation
  • POST /projects/{id}/validate - Check for errors
  • POST /projects/{id}/generate/preview - See what will be generated
  • GET /projects/{id}/generate/download - Download ZIP

Next Steps​

Troubleshooting​

401 Unauthorized:

  • Token expired or revoked
  • Check scopes match the operation (generate needs generate scope)

422 Validation Error:

  • Check request body matches schema
  • See error details in response

404 Project Not Found:

  • Check project ID is correct
  • Token might be pinned to different project
Last updated on