Skip to content

HTTP integration reference

GeoSync does not expose a conventional versioned REST API. Its public integration surface consists of an allowlisted JSON proxy, PHP form actions, authenticated HTML pages parsed by the AcuGIS CLI, file/log downloads, and two authenticated catch-all UI proxies. Paths below assume the usual /geosync-service mount; deployments may use /geosync or the web root.

All protected calls require a valid session cookie. Most action scripts return HTTP 200 even when JSON says success:false; only explicitly identified code sets error status. Do not treat 2xx as business success.

Allowlisted /api/proxy.php

Query parameters service and path select an exact allowlisted target. Unknown service is HTTP 400 text; disallowed method/path is HTTP 403 text; missing session is HTTP 401 text; connection failure is HTTP 502 text. Query parameters other than service/path are forwarded on GET. Request body is forwarded on POST. Upstream 4xx/5xx status is propagated, while a successful upstream status remains the proxy's default success status.

Analysis

  • GET api/points
  • GET api/connections
  • GET api/schemas
  • GET api/tables
  • GET api/columns
  • POST api/cluster
  • POST api/points-in-geometry
  • POST api/insights
  • POST api/save-config

api/schemas and api/tables are handled locally. They require positive integer connection_id; optional schema filters tables. Responses are, respectively, an array of schema names or {"schemas":[...],"tables":[{"schema":"...","table":"...","geom":"...?"}]}. Unknown/invalid connection produces HTTP 400 JSON.

The proxy source also branches locally for api/points and common api/cluster types (points, centroids, hull), but the reviewed api/analysis_tables.php does not define the called analysis_get_points()/analysis_run_cluster() functions. That is a verified source inconsistency; deployments may fail there unless another prepend or deployed file supplies them. Density/outliers/hotspot cluster requests and all other allowlisted analysis operations pass to the upstream service.

Form Builder

  • GET api/qfield_servers
  • GET health
  • POST generate

generate returns upstream JSON when its content type is JSON; otherwise the proxy labels it application/zip and supplies attachment name project.zip.

GeoSync

  • GET api/qfield_servers.php

The target base is the local /acugis-form-builder/geosync tree. No source for this target endpoint exists in this repository, so its response schema remains an open object.

Except for the locally implemented analysis listing shape, upstream schemas are deliberately not asserted here or in OpenAPI. They are independent services and are represented as open JSON values/binary where appropriate.

Administrative JSON form actions

Bodies are application/x-www-form-urlencoded; PHP discriminator fields are selected by presence, not necessarily a particular value. Unless noted, handlers require legacy qz_user.accesslevel == Admin (Central mode creates that synthetic Admin).

Common response: {"success":boolean,"message":string,"id"?:integer}. These handlers normally emit it without changing HTTP status.

POST /admin/action/project.php

  • save + id (0 creates), name, server_id, project_id, geopackage, pglink_id, schema, and repeated rsync_ids[].
  • delete + id.
  • pwd_vis + id: reveals provider project password in message.
  • conn_info + id: reveals PostgreSQL connection string, including password, in message.

POST /admin/action/backend.php

Fields id and op; op is exactly one of enable, disable, start, stop, restart. Controls the project's systemd service.

POST /admin/action/daemon.php

  • save + id, with daemon configuration fields; sync_admins[] is joined.
  • set + id, param, val, where param is exactly skip_init, force_init, single_run, sleep_time, or retention.

POST /admin/action/server.php

  • save, id, name, type, url, username, password.
  • delete, id; pwd_vis, id.
  • list_projects, id -> projects array of sel_label/sel_value.
  • list_geopackages, id, project_id -> geopackages.
  • list_project_geopackages, id, project_id -> both arrays.
  • project_info, id, project_id -> project_info; upstream provider shape is open.
  • list_servers -> servers with integer id, name, type, url.

admin/action/__server.php is a stale duplicate lacking list_servers and using older update behavior; it remains directly addressable but should not be used for new integrations.

POST /admin/action/pglink.php

  • save, id, name, host, port, username, password, dbname.
  • delete, id; pwd_vis, id; conn_info, id.

The last two expose credentials and must be treated as sensitive admin-only operations.

POST /admin/action/rsync.php

  • save, id, name, sync_type (remote/local). Remote fields: host, port, username, password, folder, usr_grp. Local fields: local_project_id, optional usr_grp.
  • delete, id; pwd_vis, id; conn_info, id.
  • excludes, id, excludes: writes exclusion file and redirects.
  • start, id; stop, id; log, id (HTML-escaped output).

POST /admin/action/user.php

  • save, id (-1 creates), name, email, password, accesslevel.
  • delete, id.

Only the super-admin may create/update Admin users; ownership and self-delete checks apply.

POST /admin/action/group.php

  • save, id, name, repeated project_ids[].
  • delete, id.

POST /admin/action/geonode.php

  • save, id, name, host, port, username, password, folder.
  • delete, id; pwd_vis, id; conn_info, id.

POST /admin/action/gstore.php

  • save, id, name, project_id, url, username, password, workspace.
  • delete, id; pwd_vis, id; details_info, id; store_tables, id.
  • create_layer, id, layer_name, store_tbl; optional update_geonode=t, geonode_id.

Provider/GeoServer response details are open and may be XML carried in message.

POST /admin/action/publish_web.php

Field id. Publishes/republishes a project bundle through the external publisher and returns publisher ID, viewer URL, and local timestamp on success. Failures are success:false at HTTP 200.

POST /admin/action/express.php

  • list_qfield_projects, qf_user, qf_pass, optional qf_url.
  • list_mergin_projects, mergin_user, mergin_pass, mergin_url; optional workspace, q, limit.
  • create_express, qf_proj_id, optional sleep_time, provider, and either service_id or raw qf_user, qf_pass, qf_url.

This endpoint provisions databases, credentials, provider rows, projects, and daemon files. It logs the complete POST array through error_log, so sending raw credentials has operational leakage risk. Unknown discriminator returns success:false.

Login, signup, verification

  • Local login: POST /admin/action/login.php with submit, email, pwd; redirects rather than JSON.
  • POST /admin/action/signup.php and GET /admin/action/verify.php?id=&verify= are present but blocked by the registration-disabled gate.

Files, logs, and table data

  • GET /admin/action/files.php?id=N&gpkg=NAME: owned project GeoPackage/archive attachment.
  • GET ...&img=RELATIVE_PATH[&thumb=1]: image or generated thumbnail attachment.
  • GET ...&clean=true: removes retained snapshots then redirects to the Files settings tab.
  • GET /admin/action/svc_log.php?id=N: text log attachment.
  • POST /admin/action/svc_log.php with id, op=empty: empties the service log and returns JSON.
  • POST /admin/action/table_loader.php: DataTables server-side response. GeoSync-specific fields are id, geom_tbl, geom_col (default geom), tbl_columns (URL-encoded comma list), eps, minpoints, is_centroid, and where, plus standard DataTables paging/order/search fields. It may terminate with HTTP 200 plain text for not-found/access-denied.

Authenticated HTML pages used by AcuGIS CLI

  • GET /admin/projects.php: CLI list, project resolution, and the first phase of info/status; rows expose project metadata through data-*.
  • GET /admin/project_settings.php?id=N&tab=synchronize: status, enabled flag, PID, CPU.
  • GET ...&tab=frequency: sleep_time schedule.
  • GET ...&tab=files: retained GeoPackage links used by versions.

These are HTML UI contracts parsed heuristically by the CLI, not JSON APIs. project_settings.php sets real 404 for invalid/missing project/provider and 403 for ownership denial. projects.php redirects non-admin sessions.

Other authenticated admin pages forming the UI integration surface include index.php, servers.php, databases.php, rsyncs.php, users.php, groups.php, gstores.php, geonodes.php, svc_log.php, table.php, edit_excludes.php, and the project settings pages. Legacy/auxiliary pages (services.php, daemons.php, files.php, data.php, select_db.php, registration.php, quick-start.php, group_table.php, table_whole.php, and _index.php) are HTML rather than stable programmatic APIs.

Catch-all UI proxies

  • /analysis/* requires a session, serves local safe static overrides, and otherwise GET-proxies arbitrary path/query to ANALYSIS_UPSTREAM. The code forwards only response content type, not upstream status, and does not forward non-GET request bodies/methods.
  • /formbuilder/* requires a session and GET-proxies the request URI (after removing /formbuilder) to FORMBUILDER_UPSTREAM. It likewise forwards only content type and body, not upstream status.

These broad UI proxies are distinct from /api/proxy.php's strict operation allowlist and should not be treated as documented upstream APIs.