Admin

All operations are allowed (restricted by token). Should be exclusively used on backend.

Parameters

Response

object — Returns result of write operation (confirmation).

Sample request

{
  "path": "/store/{storeId}/data/en_US/products/tshirt-blue",
  "value": {
    "name": "Blue T-shirt",
    "price": 24.9,
    "tags": [
      "apparel",
      "new"
    ]
  }
}

Writes one document at path (merged into an existing one by default). Add merge: false to replace the whole document.

Parameters

Response

object — Returns object for given path.

Sample request

{
  "path": "/store/{storeId}/data/en_US/products/tshirt-blue",
  "mask": [
    "name",
    "price"
  ]
}

Parameters

Response

object — Returns result of write operation (confirmation).

Sample request

{
  "path": "/store/{storeId}/data/en_US/products/tshirt-blue",
  "value": {
    "price": 19.9,
    "views": {
      "item": 1,
      "action": "increment"
    },
    "tags": {
      "item": "sale",
      "action": "union"
    },
    "meta.draft": {
      "action": "delete"
    }
  }
}

Plain values overwrite a field and dotted keys (meta.draft) reach into nested objects. An {item, action} object applies an operation instead - increment, union / remove for arrays, delete to drop the field.

Parameters

Response

object — Returns result of delete operation (confirmation).

Sample request

{
  "path": "/store/{storeId}/data/en_US/products/tshirt-blue"
}

Parameters

Response

object — Returns list of objects for given path and query.

Sample request

{
  "path": "/store/{storeId}/data/en_US/products",
  "query": {
    "category": "apparel",
    "price": {
      "<=": 50
    }
  },
  "order_by": {
    "price": "asc"
  },
  "limit": 20
}

A scalar in query is an equality shorthand; an operator object such as {"<=": 50} applies that Firestore operator. Page by passing the last returned id as offset.

Parameters

Response

object — Returns list of objects for given paths (keyed by path; plus _meta when meta is true).

Sample request

{
  "path": [
    "/store/{storeId}/data/en_US/products/tshirt-blue",
    "/store/{storeId}/data/en_US/products/mug-white"
  ],
  "mask": [
    "name",
    "price"
  ]
}

Up to 100 preconditioned writes applied atomically (all or nothing). Every path must lie under the request's own store (store/{storeId}/…) and pass the token's path scope as a write. create fails when the document exists; set overwrites (with precondition: {exists: false} it is a create); update takes the same dotted keys and {item, action} operations as /admin/update; update and delete may be fenced on precondition.exists or on the exact update_time an earlier commit or /admin/batch {meta: true} returned. A refused precondition answers 409 {error: "precondition_failed", index, code} (code = ALREADY_EXISTS | FAILED_PRECONDITION) and nothing is written.

Parameters

Response

object — Returns {ok: true, results: [{path, update_time}]} — one entry per write, in request order; update_time is the document's new Firestore update time (the value a later precondition takes).

Sample request

{
  "writes": [
    {
      "path": "/store/{storeId}/modules/echo/state/cursor",
      "op": "create",
      "value": {
        "n": 1
      }
    },
    {
      "path": "/store/{storeId}/orders/o-1",
      "op": "update",
      "value": {
        "modules.echo.synced": true
      },
      "precondition": {
        "update_time": "2026-09-25T10:00:00.123456000Z"
      }
    }
  ]
}

The first write creates a document (409 ALREADY_EXISTS when it is already there); the second patches an order only if it is still the version whose update_time was read back with /admin/batch {meta: true} (409 FAILED_PRECONDITION otherwise). Either failure leaves both untouched.

Parameters

Response

object — Returns result of write operation (confirmation) - "id" and "ref" of new document

Sample request

{
  "path": "/store/{storeId}/data/en_US/articles",
  "value": {
    "title": "Hello world",
    "status": "draft"
  }
}

Appends a document with a generated id to the collection at path; the response carries the new id and ref.

Parameters

Response

object — Returns {count: number} — number of documents that match the query (or the total when no query was provided).

Sample request

{
  "path": "/store/{storeId}/orders",
  "query": {
    "status": {
      "==": "ready"
    }
  }
}

Parameters

Response

object — Returns {count, sum: {field: number}, avg: {field: number | null}} from ONE aggregation query — billed one document read per 1000 matching index entries, however many fields are aggregated. The rule for dashboard numbers: aggregate, never list-and-count. With buckets the answer also carries buckets: [{count, sum, avg}, ...] (one per bucket, in order) and mode, and costs 1 + min(n, count) reads for n matching documents - nothing more when the range is empty (mode: empty), the n documents listed once when they are fewer than the buckets (docs), else one aggregation per bucket (buckets).

Sample request

{
  "path": "/store/{storeId}/orders",
  "query": "{\"status\": {\"in\": [\"completed\", \"closed\"]}, \"timestamp\": {\">=\": {\"_seconds\": 1780000000, \"_nanoseconds\": 0}}}",
  "sum": "[\"invoice.total\"]"
}

Upload a file. Send multipart/form-data with a binary file part plus text fields (dir, name?, content_type?, sid?, id?) — or JSON with dir, name, content_type?, sid?, id? and base64-encoded data. The destination is store/{sid}/files/{dir}/{id} (up to 5 levels of folders). Missing folders are auto-created.

Parameters

Response

object — Returns {path, id, entity} — an image's entity carries width / height read from the file header (PNG, JPEG, GIF, WebP, SVG; the variant shape too) — the resolved Firestore doc path, the document id, and the stored FileEntity (or FileVariant for variant uploads). Every object is stored with Content-Disposition: inline; filename="<name>" (+ RFC 5987 filename* for non-ASCII), so a browser opens it in place but saves it under its uploaded name — /assets/** on the hosted sites forwards the header. With unzip=design, returns the ingest summary {path, id, name, count, bytes, skipped, signals} instead; with entry, the entry-write summary {path, id, entry, size?, content_type?, removed?, version}.

Sample request

{
  "dir": "images",
  "name": "pixel.png",
  "content_type": "image/png",
  "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
}

The JSON shape - data is the file base64-encoded (here a 1x1 PNG). For real files send multipart/form-data with a binary file part plus the same text fields.

Start a resumable upload of a large file (above ~20 MB, up to 1 GiB) — the bytes go from the client straight to Cloud Storage, never through the API. Returns a Google Cloud Storage resumable session URI for ONE object path: PUT the file to it in chunks (Content-Range: bytes a-b/total, every chunk but the last a multiple of 256 KiB — session.chunk_bytes is the size to use; 308 = send the next chunk, 200/201 = done; after a network error PUT an empty body with Content-Range: bytes \*\/total and resume from the Range header), then call /admin/upload/finish. Same destination rules as /admin/upload (store/{sid}/files/{dir}/{id}, keep_name, replace in place with id); the object's content type, cache and disposition are fixed here. The session URI is a write credential for that one object for 7 days — keep it private. A pending session expires after 24 h.

Parameters

Response

object — Returns {upload, id, path, storage_path, session: {uri, chunk_bytes, expires}} — upload is the session id finish / abort take, path the file doc finish will write.

Sample request

{
  "dir": "video",
  "name": "showreel.mp4",
  "size": 734003200,
  "content_type": "video/mp4"
}

Finish a resumable upload: checks the object is complete (the declared size, a new object generation) and writes the file doc exactly as /admin/upload does — folder summaries, the files hook and the public URL follow as for any upload. 409 upload_incomplete = not all bytes arrived; resume the PUTs and call again. 404 upload_not_found after a lost response: read the file doc at the path start returned.

Parameters

Response

object — Returns {path, id, entity} — an image's entity carries width / height, read back from the object's header — the same result as /admin/upload.

Sample request

{
  "upload": "mhb2k1x0AbCdEfGhIjKl"
}

Create an empty folder under store/{sid}/files. Auto-creates every missing ancestor (mkdir -p). Triggers maintain the summary aggregates.

Parameters

Response

object — Returns {path, type, name} of the leaf folder doc.

Sample request

{
  "dir": "images/products",
  "name": "Products"
}