API docs by Redocly

Electric HTTP API

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 root_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.

path Parameters
root_table
required
string
Examples:
  • issues - the issues table in the public schema
  • 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.

query Parameters
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 a shape_id.

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.

shape_id
string
Example: shape_id=3833821-1721812114261

The shape ID 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 root_table.

This should be a valid PostgreSQL WHERE clause using SQL syntax.

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 root_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.

header Parameters
If-None-Match
string

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

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

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.

path Parameters
root_table
required
string
Examples:
  • issues - the issues table in the public schema
  • 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.

query Parameters
shape_id
string
Example: shape_id=3833821-1721812114261

Optional, deletes the current shape if it matches the shape_id. If not provided, deletes the current shape.

Responses