Connections

11 operations on 6 paths.

/api/connections/postgis

GETList PostGIS connections

Sign-in Session cookie or Bearer tokenMCP tool list_postgis_connections

Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Saved connections — passwords are write-only and never appear in any response.

Responses

• 200

  Success.

  application/json

  PgConnectionList

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, POST

POSTCreate a PostGIS connection

Sign-in Session cookie or Bearer tokenMCP tool create_postgis_connection

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Tests the connection first and saves only on success — nothing broken is ever stored. The password is encrypted at rest and never returned.

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• namestringrequired

• urlstring

  A Postgres URL or libpq key-value string. It is interpreted once and never stored or returned. SSL mode require maps to SSL required; prefer, disable and allow map to SSL not required (outgoing prefer, which may still negotiate TLS). Verify-ca, verify-full, unknown and conflicting repeated modes are refused before source contact, even with explicit fields. Identical repeats are accepted; empty modes are absent. Absent mode defaults to SSL required on create. Explicit fields override only a valid URL. Both string forms refuse unsupported protection requests before source contact or explicit-field overrides. Nonempty options, service and min_protocol_version are refused. Every occurrence is checked, with case-insensitive inventory names; encoding, repeats and URI fragments cannot hide a refusal. HTTP 400 invalid_request: This connection string uses the unsupported protection parameter channel_binding; Dezfil supports connection fields and SSL required or not required. The first refused parameter's canonical name replaces channel_binding; the existing SSL-mode refusal wins. Saved connections are not rechecked because their original string was never stored. See https://dezfil.io/docs/api/http-api/ (Connections) for parameter dispositions.

• hoststring

• portintegerdefault 5432

• databasestring

• usernamestring

• passwordstring

  Write-only — never echoed back.

• sslbooleandefault true

Responses

• 201

  Created and tested.

  application/json

  PgConnection

• 401403404413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS, POST

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS, POST

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/connections/postgis/{id}

PATCHUpdate a PostGIS connection

Sign-in Session cookie or Bearer tokenMCP tool update_postgis_connection

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Accepts any subset of editable fields. Connectivity changes are tested as a merged candidate before storage. A blank or omitted password keeps the stored password only when the host and port still identify the saved endpoint and the update does not turn SSL off. Changing the host or port, or turning SSL off, requires an entered password. Credentials and a submitted URL are never returned.

Parameters

• idPathrequired

  Connection id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• namestring

• urlstring

  A Postgres URL or libpq key-value string. An individually supplied field wins over its valid URL part. SSL mode require maps to SSL required; prefer, disable and allow map to SSL not required (outgoing prefer, which may still negotiate TLS). Verify-ca, verify-full, unknown and conflicting repeated modes are refused before source contact, even with explicit fields. Identical repeats are accepted; empty modes are absent. Absent mode retains the saved SSL setting on edit. Both string forms refuse unsupported protection requests before source contact or explicit-field overrides. Nonempty options, service and min_protocol_version are refused. Every occurrence is checked, with case-insensitive inventory names; encoding, repeats and URI fragments cannot hide a refusal. HTTP 400 invalid_request: This connection string uses the unsupported protection parameter channel_binding; Dezfil supports connection fields and SSL required or not required. The first refused parameter's canonical name replaces channel_binding; the existing SSL-mode refusal wins. Saved connections are not rechecked because their original string was never stored. See https://dezfil.io/docs/api/http-api/ (Connections) for parameter dispositions.

• hoststring

• portinteger

• databasestring

• usernamestring

• passwordstring

  Write-only. Blank or omitted keeps the stored password.

• sslboolean

  True requires SSL; false does not require it.

Responses

• 200

  Success.

  application/json

  PgConnection

• 401403404413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, OPTIONS, PATCH

DELETEDelete a PostGIS connection

Sign-in Session cookie or Bearer tokenMCP tool delete_postgis_connection

Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Imported snapshots stay intact; their refresh then reports the missing connection.

Parameters

• idPathrequired

  Connection id.

  string

Responses

• 204

  Deleted.

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways DELETE, OPTIONS, PATCH

Also on this path: OPTIONS under System.

/api/connections/postgis/{id}/test

POSTTest a PostGIS connection

Sign-in Session cookie or Bearer tokenMCP tool test_postgis_connection

Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Reachability, authentication, and PostGIS presence — each failure is specific.

Parameters

• idPathrequired

  Connection id.

  string

Responses

• 200

  Success.

  application/json

  PgConnection

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

/api/connections/postgis/{id}/tables

GETList relations on a PostGIS connection

Sign-in Session cookie or Bearer tokenMCP tool list_postgis_tables

Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Lists importable tables, views, and materialized views with independent PostGIS-extension membership, geometry or geography facts, and honest planner-estimate states.

Parameters

• idPathrequired

  Connection id.

  string

Responses

• 200

  The source database's tables.

  application/json

  object

  • tablesarray

    • (each item)object

      • schemastringrequired

      • tablestringrequired

      • kindstringrequired

        One of table, view, materialized_view

      • systembooleanrequired

        True only for a relation that belongs to the PostGIS extension.

      • geometryColumnstringor nullrequired

      • geometryTypestringor nullrequired

      • sridintegeror nullrequired

      • spatialKindstringor nullrequired

        One of geometry, geography, null

      • approxRowsintegeror nullminimum 0

        Omitted for a view, null for a never-analyzed table or materialized view, and numeric otherwise. Zero is a known estimate.

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/connections/postgis/{id}/preview

POSTPreview a PostGIS relation

Sign-in Session cookie or Bearer tokenMCP tool preview_postgis_relation

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Reads at most five rows from one saved connection and relation. The complete uncompressed UTF-8 JSON answer (columns and rows, excluding internal health) has a fixed 33,554,432-byte (32 MiB) ceiling; each non-geometry column value, including nested values and escaping, has a 2,097,152-byte (2 MiB) ceiling. Equality is admitted. Only source geometry/geography columns identified by source type, returned as WKT, are exempt from the cell ceiling. Text/JSON coordinates remain non-geometry. Excess refuses the whole answer with HTTP 422 query_result_too_large, without partial rows. The optional WHERE expression passes through the import guard and is applied to the preview. The caller cannot supply credentials, source SQL, or a row limit. Caller departure prevents later stages of this preview and discards late results (empty HTTP 499). Every source connection opened by the preview attachment has a 30-second per-statement ceiling; timeout answers HTTP 408 query_timeout. A departed caller's blocked source statement runs to that ceiling: the interrupt is observed between scan chunks and cannot reach a scan blocked in a libpq read. The aborted case's 35-second bound on responsive source and transport is met by the ceiling and is not evidence of interrupt propagation. The preview records nothing about the connection: neither its success nor any failure, cancellation or timeout changes the stored health, which answers for the last connection test, import or refresh. Connection tests, catalogue reads, imports and refreshes keep their existing limits.

Parameters

• idPathrequired

  Connection id.

  string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

• schemastringrequired

• tablestringrequired

• filterstring

  Optional WHERE expression evaluated on the source.

No other keys.

Responses

• 200

  The relation columns and up to five filtered source rows. Columns remain present when no row matches.

  application/json

  object

  • columnsarrayrequired

    • (each item)object

      • namestringrequired

      • typestringrequired

      • spatialKindstringor nullrequired

        One of geometry, geography, null

  • rowsarray of objectrequiredmax items 5

• 401403404413503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways OPTIONS, POST

• 408

  query_timeout: The PostGIS source query took too long.

• 499

  The caller departed. Empty response.

Also on this path: OPTIONS under System.

/api/connections/postgis/{id}/snapshots

GETList snapshots for a PostGIS connection

Sign-in Session cookie or Bearer tokenMCP tool list_postgis_snapshots

Connections are private to the authenticated account, including for administrators. Names are unique only within that account. Hidden or missing connection references return not_found before reading credentials, contacting the source or changing stored health. Imports and refreshes recheck connection ownership and account activity before committing. Snapshots and their project memberships include only the caller's datasets. A project grant never reaches a connection: one behind a dataset shared with the caller is listed, browsed, tested and used by nobody but its owner, answering not_found as one that does not exist; refreshing such a dataset is its owner's act alone; no operation transfers a connection. Returns exactly the workspace tables whose stored provenance carries this connection id, including refresh and recipe facts.

Parameters

• idPathrequired

  Connection id.

  string

Responses

• 200

  The connection's workspace snapshots.

  application/json

  object

  • snapshotsTableList

• 401403404503default

  Error with a machine-readable code and human message.

  application/json

  Error

• 405

  method_not_allowed: the method is unsupported for this path.

  application/json

  Error

  • AllowHeader

    Exactly the documented methods for this path.

    stringalways GET, HEAD, OPTIONS

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.