> ## 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.

# Public API overview

> What Katalo does and how the public API is structured: virtual staging, auth, job lifecycle, delivery, and operations.

## 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.

<CardGroup cols={3}>
  <Card title="Virtual staging" icon="sofa">
    Furnish empty or under-presented rooms with realistic listing visuals.
  </Card>

  <Card title="Property-ready outputs" icon="image">
    Return approved images your system can publish, store, or review.
  </Card>

  <Card title="Backend integration" icon="workflow">
    Embed staging into CRMs, portals, listing pipelines, and batch workers.
  </Card>
</CardGroup>

## 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.

<CardGroup cols={3}>
  <Card title="One input" icon="image">
    Each job is tied to one original source image.
  </Card>

  <Card title="Async jobs" icon="timer">
    Create returns a job immediately, then the job moves through terminal state.
  </Card>

  <Card title="Two delivery modes" icon="webhook">
    Consume a signed webhook or poll the read endpoint.
  </Card>
</CardGroup>

## When this API fits

| Integration pattern             | Why it fits                                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------------------------- |
| CRM and brokerage software      | Create or regenerate listing imagery without sending agents into the Katalo UI.                     |
| Marketplace and portal backends | Attach generation jobs to listing ingestion, moderation, or merchandising flows.                    |
| Batch and queue workers         | Create jobs from your own workers and fan results back into storage, search, or product UI.         |
| White-label product features    | Expose staging to your users while keeping credentials, policy, and delivery logic on your backend. |
| Internal reporting              | Read 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.

<Note>
  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.
</Note>

## 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

| Responsibility       | Guidance                                                                                   |
| -------------------- | ------------------------------------------------------------------------------------------ |
| Authentication       | Store the organization API key on the server and send it as a bearer token.                |
| Completion           | Use signed webhooks in production and keep polling available for recovery.                 |
| Correlation          | Use `reference`, `metadata`, and your own internal ids to map completion back to listings. |
| Asset persistence    | Copy signed output assets into your own bucket when you need durable access.               |
| Retry policy         | Use idempotency keys on writes and retry only retryable failures.                          |
| Usage reconciliation | Use usage and billing endpoints for reporting, support, and chargeback.                    |

## Quickstart

```bash theme={null}
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"
  }'
```

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="API keys" icon="key-round" href="/docs/api/api-keys">
    Create, store, rotate, and revoke credentials.
  </Card>

  <Card title="Generations" icon="wand-sparkles" href="/docs/api/generations">
    Read the create, get, and regenerate contracts.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/docs/api/webhooks">
    Verify signatures and consume completion events.
  </Card>

  <Card title="OpenAPI" icon="file-code" href="/docs/api/openapi">
    Use the machine-readable API contract.
  </Card>
</CardGroup>