{ "opencollection": "1.0.0", "info": { "name": "Electric HTTP Shape API", "version": "__PLACEHOLDER_SYNC_SERVICE_VERSION__" }, "items": [ { "info": { "name": "Shape", "type": "folder" }, "items": [ { "info": { "name": "Get Shape", "type": "http" }, "http": { "method": "GET", "url": "http://localhost:3000/v1/shape", "headers": [ { "name": "If-None-Match", "value": "" } ], "params": [ { "name": "table", "value": "", "type": "query", "description": "Root table of the shape. Must match a table in your Postgres database.\n\nCan be just a tablename, or can be prefixed by the database schema\nusing a `.` delimiter, such as `foo.issues`. If you don't provide\na schema prefix, then the table is assumed to be in the `public.` schema." }, { "name": "offset", "value": "", "type": "query", "description": "The offset in the shape stream. This is like a cursor that specifies\nthe position in the shape log to request data from.\n\nWhen making an initial request to sync a shape from scratch, you\n**must** set the `offset` to `-1`. Then, when continuing to\nsync data, you should set the `offset` to the last offset you have\nalready received, to continue syncing new data from that position\nin the stream.\n\nAlternatively, you can set `offset` to `now` to skip all historical\ndata and receive an immediate up-to-date message with the latest\ncontinuation offset. This is useful when combined with `log=changes_only`\nmode and `replica=full` for applications that don't need historical data.\n\nNote that when `offset` is not `-1` or `now` then you must also provide\nthe shape's `handle`." }, { "name": "live", "value": "", "type": "query", "description": "Whether to wait for live updates or not.\n\nWhen the `live` parameter is omitted or set to `false`, the server\nwill always return immediately, with any data it has, followed by an\nup-to-date message.\n\nOnce you're up-to-date, you should set the `live` parameter to `true`.\nThis puts the server into live mode, where it will hold open the\nconnection, waiting for new data arrive.\n\nThis allows you to implement a long-polling strategy to consume\nreal-time updates." }, { "name": "live_sse", "value": "", "type": "query", "description": "Use Server-Sent Events (SSE) for live updates instead of long polling.\n\nWhen set to `true` along with `live=true`, the server will use SSE\nto stream updates to the client. SSE provides a persistent connection\nthat allows the server to push updates as they happen, which is more\nefficient than long polling.\n\nSSE messages are sent in the standard SSE format with `data:` prefixes.\nThe stream includes data messages (shape log entries), control messages\n(up-to-date, must-refetch, etc.), and keep-alive comments sent every\n21 seconds to prevent connection timeout.\n\n**Important**: SSE requires that reverse proxies and CDNs support\nstreaming responses without buffering. Configure your proxy accordingly:\n- Nginx: `proxy_buffering off;`\n- Caddy: `flush_interval -1`\n- Apache: `flushpackets=on`\n\nSSE can only be enabled when `live` is also `true`." }, { "name": "experimental_live_sse", "value": "", "type": "query", "description": "Deprecated in favor of `live_sse`. Use `live_sse` instead.\nThis parameter will be removed in a future version." }, { "name": "cursor", "value": "", "type": "query", "description": "This is a cursor generated by the server during live requests. It helps bust caches for\nresponses from previous long-polls." }, { "name": "handle", "value": "3833821-1721812114261", "type": "query", "description": "The shape handle returned by the initial shape request.\n\nThis is a required parameter when this is not an initial sync request,\ni.e. when offset is not `-1`." }, { "name": "where", "value": "", "type": "query", "description": "Optional where clause to filter rows in the `table`.\n\nThis should be a valid PostgreSQL WHERE clause using SQL syntax.\n\nFor more details on what is supported and what is optimal,\nsee the [where clause documentation](https://electric-sql.com/docs/sync/guides/shapes#where-clause).\n\nIf this where clause uses a positional parameter, it's value must be provided under `params[n]=`\nquery parameter." }, { "name": "params", "value": "", "type": "query", "description": "Optional params to replace inside the where clause. Uses an \"exploded object\" syntax (see examples).\n\nThese values will be safely interpolated inside the where clause, so you don't need to worry about\nescaping user input when building a where clause.\n\nIf where clause mentions a posisional parameter, it becomes required to provide it." }, { "name": "columns", "value": "", "type": "query", "description": "Optional list of columns to sync in the rows from the `table`.\n\nThis is a projection setting for reducing the data sent to the client.\nIf `queryable_columns` is set, `columns` may only include columns from\nthat allow-list. If `queryable_columns` is set and `columns` is omitted,\nElectric syncs the queryable columns by default.\n\nThey should always include the primary key columns, and should be formed\nas a comma separated list of column names exactly as they are in the database schema.\n\nIf the identifier was defined as case sensitive and/or with special characters, then\\\nyou must quote it in the `columns` parameter as well." }, { "name": "queryable_columns", "value": "", "type": "query", "description": "Optional list of columns that may be referenced by subset WHERE clauses,\nsubset ORDER BY clauses, and the `columns` projection.\n\nThis is an allow-list for what client-controlled subset requests may query\nor sync. It does not force every listed column to be synced, and it does\nnot restrict the main shape WHERE clause.\n\nQueryable columns should always include the primary key columns, and should\nbe formed as a comma separated list of column names exactly as they are in\nthe database schema." }, { "name": "replica", "value": "", "type": "query", "description": "Modifies the data sent in update and delete change messages.\n\nWhen `replica=default` (the default) only changed columns are\nincluded in the `value` of an update message and only the primary\nkeys are sent for a delete.\n\nWhen set to `full` the entire row will be sent for updates and\ndeletes. `old_value` will also be present on update messages,\ncontaining the previous value for changed columns.\n\nNote that insert operations always include the full row,\nin either mode." }, { "name": "log", "value": "", "type": "query", "description": "Controls the initial data loading mode for the shape.\n\nWhen `log=full` (the default), the server creates an initial snapshot\nof all data matching the shape definition and streams it to the client\nbefore delivering real-time updates.\n\nWhen `log=changes_only`, the server skips the initial snapshot creation.\nThe client will only receive changes that occur after the shape is\nestablished, without seeing the base data. This is useful for:\n\n- Event streams where historical data isn't needed\n- Applications that fetch their initial state through `subset__*` parameters\n- Reducing initial sync time when combined with `offset=now`\n\nIn `changes_only` mode, you can use the client's `requestSnapshot` method\nto fetch subsets of data on-demand while tracking which changes to skip." }, { "name": "subset__where", "value": "", "type": "query", "description": "Optional WHERE clause to filter a subset of the shape data.\n\nPresence of this or other `subset__*` parameters in the request makes the server\nreturn a subset snapshot instead of the regular shape sync.\n\nThis allows you to fetch a specific portion of the shape's data with\nadditional filtering beyond the main shape's WHERE clause. This filter is\nalways applied in addition to the main shape's WHERE clause, so it's not possible\nto get data that doesn't match the main shape's WHERE clause." }, { "name": "subset__params", "value": "", "type": "query", "description": "Parameters for the subset WHERE clause as a JSON string.\nThe JSON should be an object mapping positional parameter numbers to their values,\nfor example: `{\"1\":\"value1\",\"2\":\"value2\"}` to replace `$1` and `$2` in the subset WHERE clause.\n\nPresence of this or other `subset__*` parameters in the request makes the server\nreturn a subset snapshot instead of the regular shape sync." }, { "name": "subset__limit", "value": "", "type": "query", "description": "Maximum number of rows to return in the subset snapshot.\n\nPresence of this or other `subset__*` parameters in the request makes the server\nreturn a subset snapshot instead of the regular shape sync.\n\nWhen `limit` or `offset` is specified, `subset__order_by` becomes required." }, { "name": "subset__offset", "value": "", "type": "query", "description": "Number of rows to skip in the subset snapshot (for pagination).\n\nPresence of this or other `subset__*` parameters in the request makes the server\nreturn a subset snapshot instead of the regular shape sync.\n\nWhen `limit` or `offset` is specified, `subset__order_by` becomes required." }, { "name": "subset__order_by", "value": "", "type": "query", "description": "ORDER BY clause for the subset snapshot, determining the row ordering. Uses\nsame syntax as `ORDER BY` clause in PostgreSQL.\n\nPresence of this or other `subset__*` parameters in the request makes the server\nreturn a subset snapshot instead of the regular shape sync.\n\nThis becomes required when using `subset__limit` or `subset__offset`." }, { "name": "secret", "value": "1U6ItbhoQb4kGUU5wXBLbxvNf", "type": "query", "description": "Secret defined by the [ELECTRIC_SECRET](https://electric-sql.com/docs/api/config#electric-secret)\nconfiguration variable. This is required unless\n`ELECTRIC_INSECURE` is set to `true`. More details are\navailable in the [security guide](https://electric-sql.com/docs/guides/security)." }, { "name": "api_secret", "value": "1U6ItbhoQb4kGUU5wXBLbxvNf", "type": "query", "description": "Deprecated in favor of the `secret` query parameter.\nWill be removed in v2." } ] }, "docs": "Load the initial data for a shape and poll for real-time updates.\n\nDefine your shape using the `table` and `where` parameters.\nUse `offset` to fetch data from a specific position in the shape\nlog and the `live` parameter to consume real-time updates." }, { "info": { "name": "Get Shape with Subset (POST)", "type": "http" }, "http": { "method": "POST", "url": "http://localhost:3000/v1/shape", "params": [ { "name": "table", "value": "", "type": "query", "description": "Root table of the shape. Must match a table in your Postgres database." }, { "name": "offset", "value": "", "type": "query", "description": "The offset in the shape stream." }, { "name": "handle", "value": "", "type": "query", "description": "The shape handle returned by the initial shape request.\nRequired when offset is not `-1`." }, { "name": "where", "value": "", "type": "query", "description": "Optional main shape WHERE clause to filter rows in the `table`." }, { "name": "columns", "value": "", "type": "query", "description": "Optional list of columns to sync in the rows." }, { "name": "queryable_columns", "value": "", "type": "query", "description": "Optional list of columns that may be referenced by subset filters,\nsubset ordering, and the columns projection. It does not restrict the\nmain shape WHERE clause." }, { "name": "replica", "value": "", "type": "query", "description": "Modifies the data sent in update and delete change messages." }, { "name": "log", "value": "", "type": "query", "description": "Controls the initial data loading mode for the shape." }, { "name": "secret", "value": "1U6ItbhoQb4kGUU5wXBLbxvNf", "type": "query", "description": "Secret defined by the [ELECTRIC_SECRET](https://electric-sql.com/docs/api/config#electric-secret)\nconfiguration variable. This is required unless\n`ELECTRIC_INSECURE` is set to `true`. More details are\navailable in the [security guide](https://electric-sql.com/docs/guides/security)." }, { "name": "api_secret", "value": "1U6ItbhoQb4kGUU5wXBLbxvNf", "type": "query", "description": "Deprecated in favor of the `secret` query parameter.\nWill be removed in v2." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Request a subset snapshot using POST with parameters in the request body.\n\n**This is the recommended method for subset snapshots.** POST requests send\nsubset parameters in the request body as JSON, avoiding URL length limits\n(HTTP 414 errors) that can occur with complex WHERE clauses or many parameters.\n\nThis is particularly important for queries with large parameter lists, such as\n`WHERE id = ANY($1)` with hundreds of IDs (common in join queries).\n\nIn Electric 2.0, GET requests for subset snaps" }, { "info": { "name": "Delete Shape", "type": "http" }, "http": { "method": "DELETE", "url": "http://localhost:3000/v1/shape", "params": [ { "name": "table", "value": "", "type": "query", "description": "The name of the table for which to delete the shape.\n\nCan be qualified by the schema name." }, { "name": "source_id", "value": "", "type": "query", "description": "The ID of the database from which to delete the shape.\nThis is required only if Electric manages several databases." }, { "name": "handle", "value": "3833821-1721812114261", "type": "query", "description": "Optional, deletes the current shape if it matches the `handle` provided. If not provided, deletes the current shape." }, { "name": "secret", "value": "1U6ItbhoQb4kGUU5wXBLbxvNf", "type": "query", "description": "Secret defined by the [ELECTRIC_SECRET](https://electric-sql.com/docs/api/config#electric-secret)\nconfiguration variable. This is required unless\n`ELECTRIC_INSECURE` is set to `true`. More details are\navailable in the [security guide](https://electric-sql.com/docs/guides/security)." }, { "name": "api_secret", "value": "1U6ItbhoQb4kGUU5wXBLbxvNf", "type": "query", "description": "Deprecated in favor of the `secret` query parameter.\nWill be removed in v2." } ] }, "docs": "Deletes the shape from the Electric sync engine.\n\nThis clears the shape log and forces any clients requesting the shape\nto create a new shape and resync from scratch.\n\n**NOTE** Delete shape only works if Electric is configured to `allow_shape_deletion`." } ] } ], "bundled": true }