API Reference

Base URL: https://www.stageproai.com/api/v1

Overview

The StagePro API lets agencies and integrators run virtual staging, interior design, and 25+ listing photo tools programmatically.

All image jobs are asynchronous: create a job, poll for status, or receive a webhook when complete.

Base URL: https://www.stageproai.com/api/v1

Authentication

Create an API key from the developer console (requires an active paid subscription).

Send your key on every request:

curl https://www.stageproai.com/api/v1/capabilities \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Create a job

POST /api/v1/jobs returns 202 with job id and status queued.

Core types: empty-room, virtual-stage, interior-design, edit.

Listing tools: type listing-tool with input.listing_tool set to a slug from GET /capabilities.

curl -X POST https://www.stageproai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "virtual-stage",
    "input": {
      "image_url": "https://example.com/room.jpg",
      "style": "modern",
      "room_type": "living-room",
      "options": { "creativity": 3, "aspect_ratio": "16:9" }
    },
    "metadata": { "listing_id": "MLS-12345", "photo_index": 1 },
    "idempotency_key": "listing-12345-photo-1-v1"
  }'

Recommended staging workflow

1. Optional: POST type empty-room → poll → get empty room output URL.

2. POST type virtual-stage with empty_room_url set to the cleared image.

3. POST /jobs/{id}/regenerate for variations on a completed job.

curl -X POST https://www.stageproai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "virtual-stage",
    "input": {
      "image_url": "https://example.com/original.jpg",
      "empty_room_url": "https://example.com/cleared.jpg",
      "style": "modern",
      "room_type": "living-room"
    }
  }'

Listing photo tools

Use type listing-tool and input.listing_tool with any slug from GET /api/v1/capabilities.

Examples: sky-enhancement, virtual-twilight, furniture-eraser, room-declutter, pool-water-enhancement.

Furniture Try-On and Magic Editor are app-only (interactive UI).

curl -X POST https://www.stageproai.com/api/v1/jobs \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "listing-tool",
    "input": {
      "image_url": "https://example.com/exterior.jpg",
      "listing_tool": "virtual-twilight"
    }
  }'

Poll for results

GET /api/v1/jobs/{id} until status is completed or failed.

Poll every 3–5 seconds. Typical jobs complete in 10–30 seconds.

curl https://www.stageproai.com/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Upload images

POST /api/v1/uploads with multipart form field file.

Use returned upload_id in job input instead of image_url.

Uploads expire after 24 hours.

curl -X POST https://www.stageproai.com/api/v1/uploads \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -F "file=@room.jpg"

Webhooks

Complete verification challenge before use.

Pass webhook_endpoint_id when creating jobs. Events: job.completed, job.failed.

Verify X-StagePro-Signature HMAC on your server.

Batch processing

POST /api/v1/batches runs the same job type across many listing photos.

Returns batch_id and job_ids. Poll GET /api/v1/batches/{id} or listen for batch.completed webhook.

Concurrency depends on your plan (2–20 parallel jobs).

curl -X POST https://www.stageproai.com/api/v1/batches \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "listing-tool",
    "input": { "listing_tool": "room-declutter" },
    "listing_id": "MLS-8842",
    "photos": [
      { "image_url": "https://example.com/kitchen.jpg", "label": "kitchen" },
      { "image_url": "https://example.com/living.jpg", "label": "living" }
    ]
  }'

Workflow templates

POST /api/v1/workflows expands a template into a batch automatically.

Templates: mls-virtual-stage, mls-room-declutter, mls-furniture-clear, mls-exterior-twilight, mls-sky-enhance, mls-interior-design.

GET /api/v1/capabilities lists all templates.

curl -X POST https://www.stageproai.com/api/v1/workflows \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "mls-virtual-stage",
    "listing_id": "MLS-8842",
    "defaults": { "style": "modern" },
    "photos": [
      { "image_url": "https://example.com/living.jpg", "label": "living", "room_type": "living-room" }
    ]
  }'

AI Design Agent

Multi-turn interior design chat with optional render. Chat is free; rendering uses credits like other jobs.

POST /api/v1/agent/sessions — upload a room photo and get a session id (24h TTL).

POST /api/v1/agent/sessions/{id}/messages — send messages (set stream: true for SSE).

POST /api/v1/agent/sessions/{id}/render — create a render job when readyToRender is true.

auto_render defaults to false. Set true on session create to auto-queue a job when the agent marks readyToRender.

# 1. Create session
curl -X POST https://www.stageproai.com/api/v1/agent/sessions \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "image_url": "https://example.com/room.jpg", "auto_render": false }'

# 2. Chat
curl -X POST https://www.stageproai.com/api/v1/agent/sessions/SESSION_ID/messages \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What would you improve in this living room?" }'

# 3. Render when readyToRender is true
curl -X POST https://www.stageproai.com/api/v1/agent/sessions/SESSION_ID/render \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "job_type": "interior-design" }'

List jobs by listing

GET /api/v1/jobs?listing_id=MLS-8842 returns all jobs for a listing (paginated).

GET /api/v1/usage returns credits, storage, and plan limits.

curl "https://www.stageproai.com/api/v1/jobs?listing_id=MLS-8842&limit=50" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

MCP server (AI agents)

Install the StagePro MCP server for Cursor, Claude Desktop, or custom agents — no REST integration code required.

Package: packages/stagepro-mcp in this repo (npm name @stagepro/mcp).

Set STAGEPRO_API_KEY and run via stdio. Tools wrap jobs, batches, workflows, and the AI design agent.

See packages/stagepro-mcp/README.md for Cursor and Claude Desktop config.

{
  "mcpServers": {
    "stagepro": {
      "command": "node",
      "args": ["/path/to/stagepro/packages/stagepro-mcp/dist/index.js"],
      "env": {
        "STAGEPRO_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Errors & limits

402 — insufficient credits

401 — invalid or revoked API key

403 — storage limit exceeded

400 — validation error

Test keys (sk_test_) return mock results without spending credits.

Available listing tools

Use type: "listing-tool" and set input.listing_tool to one of:

add-furniture
ai-furniture-background
furniture-eraser
room-declutter
material-overlay
fireplace-ignition
tv-screen-replacement
refrigerator-cleanup
landscape-design
lawn-replacement
changing-seasons
sky-enhancement
rain-to-shine
driveway-leaf-removal
driveway-car-removal
add-water-to-empty-pool
pool-water-enhancement
natural-twilight
virtual-twilight
night-to-day
ai-floorplan-visualizer
social-media-poster
sketch-to-render

Endpoints

Method	Path	Auth
GET	/api/v1/capabilities	API key
GET	/api/v1/usage	API key
POST	/api/v1/jobs	API key
GET	/api/v1/jobs?listing_id=	API key
GET	/api/v1/jobs/{id}	API key
POST	/api/v1/jobs/{id}/regenerate	API key
POST	/api/v1/batches	API key
GET	/api/v1/batches/{id}	API key
POST	/api/v1/workflows	API key
GET	/api/v1/workflows/{id}	API key
POST	/api/v1/uploads	API key
GET/POST	/api/v1/keys	Session (console)
GET/POST	/api/v1/webhooks	Session (console)