Jobs API

RoomRecast jobs represent asynchronous AI transformations. Each job tracks the requested tool, the sanitized options used to run the pipeline, the project it belongs to, and the resulting asset URL when available.

List jobs

GET /jobs

Returns the authenticated user's completed jobs ordered from newest to oldest. Pagination defaults to 20 items per page.

Name
page
Type
number
Description
1-based page to return. Defaults to 1.
Name
perPage
Type
number
Description
Number of jobs per page. Accepts per_page as an alias. Values are capped at 100 and default to 20.
Name
tool
Type
string
Description
Filter by tool identifier. Aliases toolId and tool_id are also accepted.
Name
project
Type
string
Description
Restrict jobs to a project. Accepts projectId and project_id as aliases. Supplying all or all-projects removes the filter.

{
  "items": [
    {
      "id": "job_123",
      "tool": "virtual-staging",
      "options": {
        "input": {
          "source_url": "https://cdn.roomrecast.com/uploads/2024-04-23/source.jpg",
          "instructions": "Stage as a Scandinavian living room"
        },
        "cost": 5
      },
      "project_id": "proj_default",
      "result": { "url": "results/2024-04-23/job_123.jpg" },
      "created_at": "2024-04-23T18:32:10.123456Z"
    }
  ],
  "total": 12,
  "page": 1,
  "perPage": 20
}

Get job status

GET /jobs/:id

Returns the current status of a job together with an estimated progress percentage. Completed jobs report status as completed and progress as 100.

{
  "status": "running",
  "progress": 70
}

If the job identifier does not exist the service responds with 404 and an error message.

Get job result

GET /jobs/:id/result

Retrieves a convenience payload containing the public asset URL for a finished job. When the pipeline has not finished yet the placeholder URL can be used to show a temporary preview.

{
  "url": "https://picsum.photos/seed/job_123/1024/768",
  "metadata": { "jobId": "job_123" }
}

Create tool-specific jobs

RoomRecast provides dedicated endpoints for the supported tools. Each endpoint validates the request body and delegates to the shared job creation pipeline.

All tool creation routes require authentication and expect an application/json payload. The project_id field is optional; when omitted the backend assigns the caller's default project.

Shared request body

{
  "project_id": "proj_default", // optional
  "input": {
    "source_url": "https://cdn.roomrecast.com/uploads/2024-04-23/source.jpg",
    "instructions": "...",
    "inspiration_urls": ["https://example.com/reference-1.jpg"],
    "colors": ["cream", "oak"],
    "style": "Scandinavian",
    "duration": "5", // animate only
    "motion": "pan"   // animate only
  }
}

Name
project_id
Type
string
Description
Associates the job with an existing project owned by the caller.
Name
input.source_url
Type
string
Description
Absolute URL to the source asset. This field is required for all tools. The backend also accepts input.source but normalizes it to source_url.
Name
input.instructions
Type
string
Description
Free-form instructions describing the desired transformation. Required for POST /renovate-furnish and POST /exterior; optional for other tools.
Name
input.inspiration_urls
Type
string[]
Description
Array of absolute URLs that provide additional visual guidance.
Name
input.colors
Type
string[] | string
Description
Either an array of color names or a comma-delimited string. Values are trimmed server-side.
Name
input.style
Type
string
Description
Preferred design style label.
Name
input.duration
Type
string
Description
Animation duration in seconds. Required for POST /animate. Valid values are "5" and "10".
Name
input.motion
Type
string
Description
Camera motion preset for the animation. Required for POST /animate. Accepted values are pan, dolly-in, and orbit-slight.

Available endpoints

POST /virtual-staging
POST /redecorate
POST /renovate-furnish
POST /declutter
POST /sketch-render
POST /exterior
POST /enhance
POST /animate

Each route validates the payload according to the table below.

Endpoint	Required fields	Additional validation
`/virtual-staging`	`input.source_url`	Rejects unknown keys in `input`.
`/redecorate`	`input.source_url`	Rejects unknown keys in `input`.
`/renovate-furnish`	`input.source_url`, `input.instructions`	Rejects unknown keys in `input`.
`/declutter`	`input.source_url`	Rejects unknown keys in `input`.
`/sketch-render`	`input.source_url`	Rejects unknown keys in `input`.
`/exterior`	`input.source_url`, `input.instructions`	Rejects unknown keys in `input`.
`/enhance`	`input.source_url`	Only `source_url` is accepted in `input`.
`/animate`	`input.source_url`, `input.duration`, `input.motion`	`duration` must be `5` or `10`; `motion` must be `pan`, `dolly-in`, or `orbit-slight`.

A successful request returns the standard job creation response, including the new job identifier, its status, and (when available) a CDN URL for the generated asset.