Electric HTTP API (1.0.3)

Download OpenAPI specification:Download

HTTP API to sync partial replicas of your Postgres data into local apps and services.

See the Electric documentation for more information.

Get Shape

Load the initial data for a shape and poll for real-time updates.

Define your shape using the table and where parameters. Use offset to fetch data from a specific position in the shape log and the live parameter to consume real-time updates.

query Parameters

table required	string Examples: table=issues - the issues table in the public schema table=foo.issues - the issues table in the foo schema Root table of the shape. Must match a table in your Postgres database. Can be just a tablename, or can be prefixed by the database schema using a `.` delimiter, such as `foo.issues`. If you don't provide a schema prefix, then the table is assumed to be in the `public.` schema.
offset required	string Examples: offset=-1 - sync the shape from the start offset=26800584_4 - continue syncing from offset `26800584_4` The offset in the shape stream. This is like a cursor that specifies the position in the shape log to request data from. When making an initial request to sync a shape from scratch, you must set the `offset` to `-1`. Then, when continuing to sync data, you should set the `offset` to the last offset you have already recieved, to continue syncing new data from that position in the stream. Note that when `offset` is not `-1` then you must also provide the shape's `handle`.
live	boolean Whether to wait for live updates or not. When the `live` parameter is omitted or set to `false`, the server will always return immediately, with any data it has, followed by an up-to-date message. Once you're up-to-date, you should set the `live` parameter to `true`. This puts the server into live mode, where it will hold open the connection, waiting for new data arrive. This allows you to implement a long-polling strategy to consume real-time updates.
cursor	string This is a cursor generated by the server during live requests. It helps bust caches for responses from previous long-polls.
handle	string Example: handle=3833821-1721812114261 The shape handle returned by the initial shape request. This is a required parameter when this is not an initial sync request, i.e. when offset is not `-1`.
where	string Examples: where="title='Electric'" - Only include rows where the title is 'Electric'. where="status IN ('backlog', 'todo')" - Only include rows whose status is either 'backlog' or 'todo'. Optional where clause to filter rows in the `table`. This should be a valid PostgreSQL WHERE clause using SQL syntax. For more details on what is supported and what is optimal, see the where clause documentation. If this where clause uses a positional parameter, it's value must be provided under `params[n]=` query parameter.
params	object Examples: params[1]=value1 - replace placeholder `$1` inside the where clause with `value1` Optional params to replace inside the where clause. Uses an "exploded object" syntax (see examples). These values will be safely interpolated inside the where clause, so you don't need to worry about escaping user input when building a where clause. If where clause mentions a posisional parameter, it becomes required to provide it.
columns	string Examples: columns=id,title,status - Only include the id, title, and status columns. columns=id,"Status-Check" - Only include id and Status-Check columns, quoting the identifiers where necessary. Optional list of columns to include in the rows from the `table`. They should always include the primary key columns, and should be formed as a comma separated list of column names exactly as they are in the database schema. If the identifier was defined as case sensitive and/or with special characters, then you must quote it in the `columns` parameter as well.
replica	string Enum: "default" "full" Modifies the data sent in update and delete change messages. When `replica=default` (the default) only changed columns are included in the `value` of an update message and only the primary keys are sent for a delete. When set to `full` the entire row will be sent for updates and deletes. `old_value` will also be present on update messages, containing the previous value for changed columns. Note that insert operations always include the full row, in either mode.
api_secret	string Example: api_secret=1U6ItbhoQb4kGUU5wXBLbxvNf Secret defined by the ELECTRIC_SECRET configuration variable. This is required unless `ELECTRIC_INSECURE` is set to `true`. More details are available in the security guide.

header Parameters

If-None-Match

string

Re-validate the shape if the etag doesn't match.

Responses

Response samples

200
409
429

Content type

application/json

[{"headers": {"operation": "insert",
"lsn": 1234,
"op_position": 0
},
"key": "issue-1",
"value": {"id": "issue-1",
"title": "Electric",
"status": "backlog"
}
},
{"headers": {"operation": "insert",
"lsn": 1234,
"op_position": 7
},
"key": "issue-2",
"value": {"id": "issue-2",
"title": "Hello",
"status": "backlog"
}
},
{"headers": {"control": "up-to-date"
}
}
]

Delete Shape

Deletes the shape from the Electric sync engine.

This clears the shape log and forces any clients requesting the shape to create a new shape and resync from scratch.

NOTE Delete shape only works if Electric is configured to allow_shape_deletion.

query Parameters

table required	string Examples: table=issues - the issues table in the public schema table=foo.issues - the issues table in the foo schema The name of the table for which to delete the shape. Can be qualified by the schema name.
source_id	string The ID of the database from which to delete the shape. This is required only if Electric manages several databases.
handle	string Example: handle=3833821-1721812114261 Optional, deletes the current shape if it matches the `handle` provided. If not provided, deletes the current shape.
api_secret	string Example: api_secret=1U6ItbhoQb4kGUU5wXBLbxvNf Secret defined by the ELECTRIC_SECRET configuration variable. This is required unless `ELECTRIC_INSECURE` is set to `true`. More details are available in the security guide.