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

header Parameters

If-None-Match

string

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

Responses

Response samples

200
409

Content type

application/json

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

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.

WARNING Delete shape should only be used in development and 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.