Getting started
Public API overview
How the Katalo public API is structured: auth, job lifecycle, delivery, and operations.
Overview
Integrate Katalo from your backend
Submit one source image, create a job, wait for completion, and read back one primary output plus an optional approved alternate.
This documentation is for backend and platform engineers. It covers request contracts, authentication, webhook delivery, operational limits, and the OpenAPI source contract.
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.
1
source image per job
5
core public endpoints
2
delivery modes: polling or webhook
Input
One original image per request.
Result
A job plus signed output URLs.
Delivery
Poll or receive a webhook.
Scope
When this API is a good fit
Use the public API when Katalo needs to run inside your own product, queue, or operational workflow.
| 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. |
Flow
Request flow
A normal integration has five steps: authenticate, ingest the source, create the generation, wait for completion, and consume outputs.
Ingest the source image
Create a job
Wait for a terminal status
Read the outputs
Regenerate when needed
Input
Source ingest is its own API step
The recommended production contract is two-step: create a reusable source asset first, then create generations from that asset.
Recommended path
Compatibility path
Reuse
Contract
Rules to design around
The public API is intentionally narrower than the internal generation pipeline. Build against the public contract, not internal assumptions.
One source image per job
Only publishable outputs are returned
Signed URLs are temporary
Request validity depends on workflow
Surfaces
Product surfaces
Katalo has more than one product surface. This documentation covers only the public server-to-server API.
| Surface | What it is |
|---|---|
| Web app | Interactive staging inside the Katalo product. |
| API | Server-to-server integration for your backend, workers, and webhooks. |
| Managed service | Manual or assisted workflows outside the public API path. |
Integration
What your integration owns
Katalo handles generation. Your system still owns auth, correlation, delivery handling, and asset persistence.
Authentication
Asynchronous completion
Correlation
Asset persistence
Retry policy
Usage reconciliation
Quick start
Ingest a source asset, then send your first job
Start by creating a source asset, wait until it is ready, then create the generation from `source_asset_id`.
curl https://app.katalo.ai/api/v1/source-assets \
-H "Authorization: Bearer $KATALO_API_KEY" \
-H "Idempotency-Key: listing-123-source-001" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://cdn.example.com/listing.jpg"
}'
# poll GET /api/v1/source-assets/{ingest_id} until source_asset_id is present
curl https://app.katalo.ai/api/v1/generations \
-H "Authorization: Bearer $KATALO_API_KEY" \
-H "Idempotency-Key: listing-123-generation-001" \
-H "Content-Type: application/json" \
-d '{
"source_asset_id": "src_...",
"workflow": "staging",
"capture_type": "photo",
"mode": "refurnish",
"room_types": ["Living Room", "Kitchen"],
"style_preset": "modern",
"reference": "listing-123-lr-1"
}'Inline create is compatibility only
`POST /api/v1/generations` still accepts one multipart file or `source_url`, but that path is transitional and may return `status=ingesting` before the job reaches `queued`.
Multipart requests still take one image
Multipart requests carry one file field. The API does not accept an array of uploads.
Response shape
What comes back
Create and get return the same job envelope: public ids, workflow state, optional failure details, and signed output URLs.
job_id
Stable public id for the generation job. Use it to poll status or regenerate from the same source asset.
outputs
The returned images. Each output includes a signed URL that expires after 15 minutes.
failure
A terminal error payload with a machine-readable code and retry hint.
metadata
Your original metadata, echoed back without modification.
Dashboard
What lives in the dashboard
The dashboard owns credentials and webhook defaults. These docs own the request and response contract.
Keep the responsibilities separate
Use the dashboard to issue and rotate keys, set default webhook destinations, and manage organization-level API access. Use the docs and OpenAPI file for field-level behavior.
Supported flows
Supported operations
The public API has two workflows and one follow-up operation on an existing job.
| Flow | When to use it | Notes |
|---|---|---|
| staging | Use this for virtual staging. Required and allowed fields depend on `capture_type`. | This is the default path for most integrations. |
| pro_capture | Use this for photo-only capture jobs with a narrower request shape. | Rejects `mode`, `room_types`, and `style_preset`. |
| regenerate | Create a new job from an existing `job_id` while reusing the same source asset. | Allowed overrides depend on the parent job’s workflow and capture type. |
Next
Continue with these pages
Most teams read key management, generations, webhooks, and reliability in that order.
Reliability & SLAs
Usage & billing
OpenAPI reference