Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.katalo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
What Katalo does

Katalo is an AI virtual staging platform for real-estate imagery. It turns empty, dated, or unfinished property photos into photorealistic, listing-ready images so agents, brokerages, portals, and real-estate software teams can market properties without physical staging or manual Photoshop production. The API lets your backend submit one source image, choose the workflow and style, wait for completion, and read back one primary output plus an optional approved alternate.

Virtual staging

Furnish empty or under-presented rooms with realistic listing visuals.

Property-ready outputs

Return approved images your system can publish, store, or review.

Backend integration

Embed staging into CRMs, portals, listing pipelines, and batch workers.

​
Integrate Katalo from your backend

This documentation is for backend and platform engineers. The public API is server-to-server only: your backend owns the API key, ingests source assets, creates jobs, receives results by webhook or polling, and decides whether to persist signed output assets.

One input

Each job is tied to one original source image.

Async jobs

Create returns a job immediately, then the job moves through terminal state.

Two delivery modes

Consume a signed webhook or poll the read endpoint.

​
When this API fits

Integration patternWhy it fits
CRM and brokerage softwareCreate or regenerate listing imagery without sending agents into the Katalo UI.
Marketplace and portal backendsAttach generation jobs to listing ingestion, moderation, or merchandising flows.
Batch and queue workersCreate jobs from your own workers and fan results back into storage, search, or product UI.
White-label product featuresExpose staging to your users while keeping credentials, policy, and delivery logic on your backend.
Internal reportingRead usage summaries and billing ledger entries for reconciliation and support tooling.

​
Request flow

  1. Ingest the source image with POST /api/v1/source-assets.
  2. Poll GET /api/v1/source-assets/{ingest_id} until source_asset_id is ready.
  3. Create a generation with POST /api/v1/generations.
  4. Wait for succeeded or failed using a webhook or GET /api/v1/generations/{job_id}.
  5. Consume signed output URLs immediately, or copy assets into your own storage for durable access.
  6. Regenerate with POST /api/v1/generations/{job_id}/regenerate when you need another approved output from the same source.
Inline file and source_url submission on POST /api/v1/generations still works as a compatibility path, but the production contract should create a reusable source asset first.

​
Contract rules

  • A job always uses one original image.
  • Public responses include only publishable outputs: the primary approved output and, if requested, at most one approved alternate.
  • Signed output URLs are temporary. Copy images into your own storage if they need to remain available.
  • Request validity depends on workflow and capture_type; some fields are required, optional, or explicitly not allowed.

​
Your integration owns

ResponsibilityGuidance
AuthenticationStore the organization API key on the server and send it as a bearer token.
CompletionUse signed webhooks in production and keep polling available for recovery.
CorrelationUse reference, metadata, and your own internal ids to map completion back to listings.
Asset persistenceCopy signed output assets into your own bucket when you need durable access.
Retry policyUse idempotency keys on writes and retry only retryable failures.
Usage reconciliationUse usage and billing endpoints for reporting, support, and chargeback.

​
Quickstart

curl https://app.katalo.ai/api/v1/source-assets \
  -X POST \
  -H "Authorization: Bearer $KATALO_API_KEY" \
  -H "Idempotency-Key: source-listing-123-lr-1" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/listings/empty-living-room.jpg"
  }'

curl https://app.katalo.ai/api/v1/generations \
  -X POST \
  -H "Authorization: Bearer $KATALO_API_KEY" \
  -H "Idempotency-Key: generation-listing-123-lr-1" \
  -H "Content-Type: application/json" \
  -d '{
    "source_asset_id": "src_01JXSRCABCDEFGHIJKL012345",
    "workflow": "staging",
    "capture_type": "photo",
    "mode": "refurnish",
    "room_types": ["Living Room", "Kitchen"],
    "style_preset": "modern",
    "include_alternates": true,
    "reference": "listing-123-lr-1",
    "metadata": {
      "listing_id": "listing-123",
      "partner": "acme"
    },
    "webhook": {
      "url": "https://partner.example.com/webhooks/katalo"
    }
  }'

​
Continue reading

API keys

Create, store, rotate, and revoke credentials.

Generations

Read the create, get, and regenerate contracts.

Webhooks

Verify signatures and consume completion events.

OpenAPI

Use the machine-readable API contract.