API Reference

Complete endpoint documentation for the DomeAgent Enterprise API.

Base URL

https://staging-api.domeagent.com.au/v1

All requests require an X-API-Key header. See Authentication. Switch environments using the toggle in the top nav.

Jobs

GET/v1/jobs200

List all jobs for your organization with optional filters and pagination.

Query Parameters

Parameter	Type	Required	Description
`limit`	integer (1-100)	No	Results per page. Default: 50
`offset`	integer (≥0)	No	Pagination offset. Default: 0
`status`	string	No	Filter by status: queued, running, awaiting_input, completed, failed
`job_type`	string	No	Filter by job type

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "job_type": "drone_footage",
      "status": "completed",
      "input": { "address": "123 Collins St, Melbourne" },
      "output": { "video_url": "https://..." },
      "created_at": "2026-02-09T10:00:00.000Z",
      "updated_at": "2026-02-09T10:02:30.000Z",
      "completed_at": "2026-02-09T10:02:30.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T12:00:00.000Z"
  }
}

GET/v1/jobs/{jobId}200

Retrieve a specific job by ID. Use this to poll for async job completion.

Path Parameters

Parameter	Type	Required	Description
`jobId`	string (UUID)	Yes	The job ID returned when the job was created

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "job_type": "drone_footage",
    "status": "completed",
    "input": { "address": "123 Collins St, Melbourne" },
    "output": {
      "video_url": "https://...",
      "thumbnail_url": "https://...",
      "duration": 12.5
    },
    "created_at": "2026-02-09T10:00:00.000Z",
    "updated_at": "2026-02-09T10:02:30.000Z",
    "completed_at": "2026-02-09T10:02:30.000Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T12:00:00.000Z"
  }
}

Content Generation

POST/v1/drone-footage/generate202

Generate aerial drone footage for a property address. Returns a job ID for async polling.

Request Body

Parameter	Type	Required	Description
`address`	string	Yes	Full property address
`options.direction`	string	No	Camera direction: original, north, south, east, west, topdown_zoomout, topdown_zoomin

Request Example

{
  "address": "123 Collins Street, Melbourne VIC 3000",
  "options": {
    "direction": "north"
  }
}

Response

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:00:00.000Z"
  }
}

POST/v1/image-enhance/generate202

Enhance a property image using AI. The image URL must be publicly accessible.

Request Body

Parameter	Type	Required	Description
`image_url`	string (URL)	Yes	Publicly accessible HTTP(S) image URL
`options.prompt`	string	No	Custom enhancement prompt

Request Example

{
  "image_url": "https://example.com/property-photo.jpg",
  "options": {
    "prompt": "Brighten the sky and enhance lawn color"
  }
}

Response

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:00:00.000Z"
  }
}

POST/v1/virtual-staging/generate202

Virtually stage an empty room with furniture and decor.

Request Body

Parameter	Type	Required	Description
`image_url`	string (URL)	Yes	Publicly accessible HTTP(S) image of empty room
`room_type`	string	Yes	Room type (e.g., living_room, bedroom, kitchen, bathroom, dining_room)
`options.style_prompt`	string	No	Custom style prompt (e.g., 'modern minimalist')

Request Example

{
  "image_url": "https://example.com/empty-room.jpg",
  "room_type": "living_room",
  "options": {
    "style_prompt": "Modern Scandinavian with warm wood tones"
  }
}

Response

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:00:00.000Z"
  }
}

POST/v1/video-clip/generate202

Generate a cinematic video clip from a single property image.

Request Body

Parameter	Type	Required	Description
`image_url`	string (URL)	Yes	Publicly accessible HTTP(S) image URL
`options.prompt`	string	No	Motion/style prompt for the video
`options.creativity_level`	string	No	low, medium, or high. Default: medium
`options.frame_mode`	string	No	first (image is first frame) or last (image is last frame). Default: first
`options.duration`	integer (3-10)	No	Video duration in seconds. Default: 5

Request Example

{
  "image_url": "https://example.com/property-front.jpg",
  "options": {
    "prompt": "Slow cinematic pan across the facade",
    "creativity_level": "medium",
    "duration": 5
  }
}

Response

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:00:00.000Z"
  }
}

Markup Generation (Multi-Step)

Markup generation is a multi-step workflow. See the Markup Guide for a full walkthrough.

POST/v1/markup/generate202

Step 1: Start a markup generation job for a property address.

Request Body

Parameter	Type	Required	Description
`address`	string	Yes	Full property address
`options`	object	No	Additional generation options

Response

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:00:00.000Z"
  }
}

GET/v1/markup/jobs/{jobId}200

Step 2: Poll until status is awaiting_input, then retrieve orientation variants.

Path Parameters

Parameter	Type	Required	Description
`jobId`	string (UUID)	Yes	The markup job ID

Response (when awaiting_input)

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "job_type": "markup",
    "status": "awaiting_input",
    "input": { "address": "123 Collins St, Melbourne" },
    "output": {
      "orientation_variants": [
        {
          "key": "bottom",
          "preview_url": "https://...",
          "enhanced_url": "https://..."
        },
        {
          "key": "left",
          "preview_url": "https://...",
          "enhanced_url": "https://..."
        }
      ]
    },
    "created_at": "2026-02-09T10:00:00.000Z",
    "updated_at": "2026-02-09T10:01:15.000Z",
    "completed_at": null
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:01:20.000Z"
  }
}

POST/v1/markup/jobs/{jobId}/select200

Step 3: Select a preferred orientation from the variants.

Request Body

Parameter	Type	Required	Description
`orientation`	string	Yes	Orientation key from the variants (e.g., 'bottom', 'left')

Response

{
  "data": {
    "status": "selected",
    "selected_url": "https://..."
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:02:00.000Z"
  }
}

POST/v1/markup/jobs/{jobId}/annotate200

Step 4: Submit boundary annotation with annotated and clean images.

Request Body

Parameter	Type	Required	Description
`annotated_image_url`	string (URL)	Yes	URL of the annotated boundary image
`clean_image_url`	string (URL)	Yes	URL of the clean (unannotated) image

Response

{
  "data": {
    "status": "completed"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:03:00.000Z"
  }
}

POST/v1/markup/jobs/{jobId}/video202

Step 5 (optional): Generate a cinematic video from the completed markup.

Request Body

Parameter	Type	Required	Description
`options`	object	No	Additional video generation options

Response

{
  "data": {
    "job_id": "661f9500-f30c-52e5-b827-557766551111",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:04:00.000Z"
  }
}

Usage & Billing

GET/v1/usage200

View your usage events and cost summary for a given date range.

Query Parameters

Parameter	Type	Required	Description
`from`	string (YYYY-MM-DD)	No	Start date. Default: first day of current month
`to`	string (YYYY-MM-DD)	No	End date. Default: today

Response

{
  "data": {
    "events": [
      {
        "id": "evt_abc123",
        "event_type": "drone_footage.generate",
        "unit_price_cents": 250,
        "status": "completed",
        "created_at": "2026-02-09T10:00:00.000Z"
      }
    ],
    "summary": {
      "total_events": 156,
      "total_cost_cents": 39000,
      "from": "2026-02-01",
      "to": "2026-02-09"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T12:00:00.000Z"
  }
}

Error Responses

All endpoints return errors in a consistent format. See Error Codes for the full list.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "address is required"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-09T10:00:00.000Z"
  }
}

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request body or parameters
400	`INVALID_URL`	Provided URL is not accessible
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Insufficient permissions
403	`FEATURE_DISABLED`	Endpoint not enabled for your org
403	`INSUFFICIENT_QUOTA`	Usage quota exceeded
404	`JOB_NOT_FOUND`	Job ID does not exist
409	`JOB_IN_PROGRESS`	A job for this resource is already running
429	`RATE_LIMITED`	Too many requests
500	`INTERNAL_ERROR`	Unexpected server error