Developer Reference · Preview specification

The Vesta API

The design of Vesta’s planned public API for batch staging and disclosure records.

This is the specification for Vesta’s planned public API. It is not live yet: no workspace tokens are issued and the endpoints below do not respond. If you want early access, or need to integrate before it ships, talk to the studio.

Base URL

Not yet issued

Auth

Bearer · workspace token

Content-Type

application/json

POST/api/pipeline/batch

Submit a staging batch

Enqueues a set of source frames for spatial-coherence staging. Returns a trace identifier used to subscribe to status updates and retrieve the signed audit bundle when the batch completes.

Request

json

{
  "listingId": "VST-A14-0921",
  "frames": [
    { "sourceKey": "uploads/2026/05/25/frame-01.jpg", "sha256": "9f3c…" },
    { "sourceKey": "uploads/2026/05/25/frame-02.jpg", "sha256": "44a1…" }
  ],
  "options": {
    "style":        "editorial-minimal",
    "watermark":    true,
    "preserveSun":  true
  }
}

Response

json

{
  "traceId":        "TRC-8A41-22F1-90B7",
  "status":         "queued",
  "frameCount":     2,
  "estimatedMs":    142000,
  "subscribeUrl":   "wss://api.vesta.studio/socket",
  "auditBundleUrl": null
}

GET/api/pipeline/batch/:traceId

Read batch status

Returns the current pipeline state for a previously submitted batch. Once status transitions to success, the signed audit bundle URL is populated.

Response

json

{
  "traceId":        "TRC-8A41-22F1-90B7",
  "status":         "success",
  "frameCount":     2,
  "framesProcessed": 2,
  "durationMs":     141204,
  "auditBundleUrl": "https://cdn.vesta.studio/audit/TRC-8A41-22F1-90B7.json",
  "complianceScore": 0.984
}

POST/api/vectors/search

Query the embedding index

Performs a nearest-neighbour search against the staged-imagery embedding index. Useful for surfacing structurally similar interiors across the brokerage portfolio.

Request

json

{
  "queryFrameKey": "uploads/2026/05/25/frame-01.jpg",
  "topK":          8,
  "filter": {
    "style":     "editorial-minimal",
    "minScore":  0.72
  }
}

Response

json

{
  "matches": [
    {
      "listingId": "VST-A14-0918",
      "frameKey":  "renders/VST-A14-0918/frame-04.jpg",
      "score":     0.891
    },
    {
      "listingId": "VST-A14-0894",
      "frameKey":  "renders/VST-A14-0894/frame-12.jpg",
      "score":     0.844
    }
  ],
  "took_ms": 47
}

DELETE/api/pipeline/batch/:traceId

Revoke an in-flight batch

Aborts a queued or processing batch. Already-emitted renders remain in the audit ledger and are marked revoked.

Response

json

{
  "traceId":  "TRC-8A41-22F1-90B7",
  "status":   "revoked",
  "revokedAt": "2026-05-25T22:01:13.448Z"
}