REST API Reference (v1)¶

OpenECPDS exposes a versioned JSON REST API that allows external systems to manage incoming users, destinations, metadata, monitoring data, and data files programmatically.

Base URL¶

https://<host>/ecpds/v1/

All endpoints are mounted under the /ecpds/ context of the Monitor/Master server. The API version prefix v1 is part of every path.

Authentication¶

All endpoints (except GET /v1/version) require HTTP Basic Authentication.

Supply credentials in the Authorization header:

Authorization: Basic <base64(username:password)>

curl -u apiuser:secret https://<host>/ecpds/v1/version

curl -sk -u apiuser:secret https://<host>/ecpds/v1/monitoring/summary | jq .
# or, without jq:
curl -sk -u apiuser:secret https://<host>/ecpds/v1/monitoring/summary | python3 -m json.tool

curl -sk -u apiuser:secret https://<host>/ecpds/v1/monitoring/summary \
  | jq '.stepStatusList[] | {product, time, step, type, status}'

import requests
resp = requests.get(
    "https://<host>/ecpds/v1/version",
    auth=("apiuser", "secret"),
    verify=True,
)
print(resp.json())

If the Authorization header is missing or malformed, the API returns 401 Unauthorized.

Permission Configuration¶

API users and their allowed operations can also be defined in the OpenECPDS properties file under the [API] section — this is mainly useful for bootstrapping the first client(s) before the web interface is available, or for automated deployments that provision configuration files. Entries found here are migrated into the database-backed API client store on startup (and then manageable from /do/user/api like any other client). The format is:

[API]
<username>=<password>:<service-regex>

Service names are the internal method names listed in each endpoint's description below.

Examples¶

Allow a user to call all services:

[API]
myuser=mysecret:.*

Allow a user only to read destination metadata (GET operations):

[API]
readonly=readpass:getDestinationMetaFields|getDestinationMetaValuesByDestination

Allow a user to manage incoming users and associations, but nothing else:

[API]
incomingmgr=pass123:incomingUser.*|incomingCategory.*|incomingAssociation.*

Allow a user to submit data files and manage destination backups:

[API]
datapipeline=pipepass:datafilePut|datafileDel|datafileSize|destinationBackup.*

Allow a user to only read the product monitoring summary (e.g. an operator-facing tool or dashboard):

[API]
ops=opspass:monitoringSummaryList

Response Format¶

All responses are JSON objects. Successful responses include "status": "ok":

{ "status": "ok", "fieldName": ... }

Error responses include "status": "error" and a "message" field:

{ "status": "error", "message": "User not authorized" }

HTTP-level errors (auth failures, missing parameters) return standard HTTP status codes (400, 401, 403, 412) with a plain-text body.

Sensitive Fields¶

Some objects returned by this API carry credentials or other sensitive values: a Host's password (GET /v1/destination/backup[/{name}]), an incoming user's password (GET /v1/incoming/user/list), a web user's password (GET /v1/web/user/list), and any destination-metadata field configured with type password — both its stored value (GET /v1/destination/{name}/metadata) and its field-level defaultValue (GET /v1/destination/metadata/fields).

By default, these values are omitted from the JSON response even when the client is otherwise permitted to call the endpoint. To include them, grant the client the showSensitiveInfo service permission (a checkbox in the Data Visibility group on /do/user/api/{clientId}, or .* in the [API] regex). This permission is independent from — and does not replace — the permission needed to call the endpoint itself; it only changes what an already-successful response contains.

Endpoints¶

System¶

GET /v1/version¶

Returns the current OpenECPDS version. No authentication required.

Parameters: none

Response:

{ "status": "ok", "version": "6.7.7-20240701" }

Service name: (none — open to all)

Incoming Users¶

These endpoints manage incoming user accounts (data consumers/publishers) and their category and destination associations.

POST /v1/incoming/user/add¶

Creates a new incoming user with a password.

Query parameters:

Service name: incomingUserAdd

Response:

{ "status": "ok" }

POST /v1/incoming/user/add2¶

Creates or updates an incoming user without a password (password set separately or via other means).

Query parameters:

Service name: incomingUserAdd2

GET /v1/incoming/user/list¶

Lists all incoming users, optionally filtered by destination.

Query parameters:

Service name: incomingUserList

Each user's password field is included only if the client also has the showSensitiveInfo permission (see Sensitive Fields) — omitted otherwise.

Response:

{
  "status": "ok",
  "incomingUserList": ["user1", "user2"]
}

DELETE /v1/incoming/user/del/{id}¶

Deactivates (soft-deletes) an incoming user.

Path parameters:

Service name: incomingUserDel

Response:

{ "status": "ok" }

POST /v1/incoming/category/add¶

Assigns one or more categories to an incoming user. The request body is a JSON array of category names.

Query parameters:

Request body: Content-Type: application/json

["category1", "category2"]

Service name: incomingCategoryAdd

Response:

{ "status": "ok" }

POST /v1/incoming/association/add¶

Associates an incoming user with a destination.

Query parameters:

Service name: incomingAssociationAdd

Response:

{ "status": "ok" }

DELETE /v1/incoming/association/del¶

Removes the association between an incoming user and a destination.

Query parameters:

Service name: incomingAssociationDel

Response:

{ "status": "ok" }

GET /v1/incoming/association/list¶

Lists all destination associations for an incoming user.

Query parameters:

Service name: incomingAssociationList

Response:

{
  "status": "ok",
  "associationList": ["destination_a", "destination_b"]
}

Web Users¶

These endpoints manage web (admin console) user accounts — the identity used to log into the ECPDS web interface itself, gated by its own Category/Resource ACL. This is a distinct concept from an Incoming User (a data-portal/dissemination account, managed above): a web user's password lets someone sign in to the console, but a freshly created one is granted no ACL category, so it cannot access anything there until an administrator assigns it a role from /do/user/user — these endpoints create/list/delete the account only, never its roles.

POST /v1/web/user/add¶

Creates a new web user with a password, or updates an existing one.

Query parameters:

Service name: webUserAdd

Response:

{ "status": "ok" }

POST /v1/web/user/add2¶

Creates a new web user with a generated password. Fails if the id already exists.

Query parameters:

Service name: webUserAdd2

Response:

{ "status": "ok", "pass": "aB3xQ9zK" }

GET /v1/web/user/list¶

Lists all active web users, optionally filtered by ACL category.

Query parameters:

Service name: webUserList

Each user's password field is included only if the client also has the showSensitiveInfo permission (see Sensitive Fields) — omitted otherwise.

Response:

{
  "status": "ok",
  "userList": ["user1", "user2"]
}

DELETE /v1/web/user/del/{id}¶

Deletes a web user account.

Path parameters:

Service name: webUserDel

Response:

{ "status": "ok" }

Destinations¶

GET /v1/destination/list¶

Returns a list of destinations, optionally filtered.

Query parameters:

Service name: destinationList

Response:

{
  "status": "ok",
  "destinationList": [
    { "name": "dest_a", "type": 0, "country": "DE", ... },
    ...
  ]
}

GET /v1/destination/{name}¶

Returns details for a single destination.

Path parameters:

Service name: (basic auth only — no per-service check)

Response:

{
  "status": "ok",
  "destination": { "name": "dest_a", "type": 0, ... }
}

GET /v1/destination/type/list¶

Returns all available destination types.

Parameters: none

Service name: (basic auth only)

Response:

{
  "status": "ok",
  "typeList": ["dissemination", "acquisition", ...]
}

GET /v1/destination/country/list¶

Returns all countries that have at least one destination associated.

Parameters: none

Service name: destinationCountryList

Response:

{
  "status": "ok",
  "countryList": ["DE", "FR", "GB", ...]
}

Destination Metadata¶

The metadata endpoints allow reading and writing structured metadata fields attached to destinations. Fields are defined globally via the Metadata Field Definitions admin page (/do/admin/metafields). All metadata is grouped by category (e.g. General, Contacts, Data, Storage, Documentation, Procedures, Alerts) in both GET responses and PUT request bodies.

See Destination Metadata for why this feature exists, the field types available, and how the defaultValue/editable locking mechanism is meant to be used.

GET /v1/destination/metadata/fields¶

Returns all active metadata field definitions (name, label, type, category, default value, etc.). Use this as a reference catalogue of all available field names, their types, and their current default values.

Parameters: none

Service name: getDestinationMetaFields

Response:

{
  "success": "yes",
  "fields": [
    {
      "id": 1,
      "name": "organisationWebPage",
      "label": "Organisation Web Page",
      "type": "url",
      "category": "General",
      "tooltip": "The organisation's public web page",
      "defaultValue": null,
      "editable": true,
      "maxOccurs": 1,
      "position": 0,
      "active": true
    },
    {
      "id": 8,
      "name": "computerOperations",
      "label": "Computer Operations",
      "type": "contact",
      "category": "Contacts",
      "tooltip": null,
      "defaultValue": null,
      "editable": true,
      "maxOccurs": -1,
      "position": 1,
      "active": true
    },
    {
      "id": 12,
      "name": "opsviewNotes",
      "label": "Opsview Notes",
      "type": "markdown",
      "category": "Documentation",
      "tooltip": "Information for operators, rendered as HTML and included in the Opsview note when flagged",
      "defaultValue": "# Operational Notes\n\n_Nothing recorded yet._",
      "editable": true,
      "maxOccurs": 1,
      "position": 0,
      "active": true
    },
    ...
  ]
}

defaultValue is the value used to seed a field the first time it's associated with a destination; editable says whether a destination can override it (false means the field is locked and always shows/exports this defaultValue, kept live in sync with it — see PUT /v1/destination/{name}/metadata below). A password-type field's defaultValue is redacted (null) unless the client has the showSensitiveInfo permission (see Sensitive Fields).

Field types:

GET /v1/destination/{name}/metadata¶

Returns all metadata values for a destination grouped by category. Fields with no value are included as null. Multi-value fields (e.g. multiple contacts) are returned as arrays. A field that is not editable at the destination level (see editable under GET /v1/destination/metadata/fields) always reflects that field definition's current defaultValue here, live — never a stale or stored per-destination value.

A separate includeInNotes object, grouped the same way as metadata, says which fields are currently flagged to be included when this destination's metadata is exported to Opsview as notes (see POST on the Destination Metadata page's Export Notes button) — true/false per field name.

Path parameters:

Service name: getDestinationMetaValuesByDestination

Fields of type password are included only if the client also has the showSensitiveInfo permission (see Sensitive Fields) — omitted entirely otherwise.

Response:

{
  "success": "yes",
  "destination": "hourly_aq",
  "exportedAt": "2026-07-13T09:00:00Z",
  "metadata": {
    "General": {
      "organisationWebPage": "https://www.example.org/",
      "SADNumber": null,
      "contractId": null,
      "generalComments": null
    },
    "Contacts": {
      "computerOperations": [
        { "name": "Alice Smith", "email": "alice@example.org", "phone": "+44 1234 567890", "fax": null },
        { "name": "Bob Jones",  "email": "bob@example.org",   "phone": null,               "fax": null }
      ],
      "meteorologists": null,
      "switchboard": { "name": "Switchboard", "phone": "+44 1234 000000" },
      "mailGroup": { "name": "ops-list", "email": "ops@example.org" }
    },
    "Documentation": {
      "documentationUrl": "https://docs.example.org/",
      "opsviewNotes": "# Operational Notes\n\n_Nothing recorded yet._"
    }
  },
  "includeInNotes": {
    "General": { "organisationWebPage": false, "SADNumber": false, "contractId": false, "generalComments": false },
    "Contacts": { "computerOperations": false, "meteorologists": false, "switchboard": false, "mailGroup": false },
    "Documentation": { "documentationUrl": false, "opsviewNotes": true }
  }
}

PUT /v1/destination/{name}/metadata¶

Replaces all metadata values for a destination. Existing values are removed and replaced atomically. The request body must use the same grouped-by-category structure as the GET response — you can GET, modify values, and PUT back without any format transformation.

Fields set to null or omitted are skipped (no value stored). Multi-value fields accept either a single value or an array.

A field that is not editable at the destination level (editable: false) silently ignores any value submitted for it in metadata (logged server-side, not an error) and always keeps using the field definition's current defaultValue instead — consistent with it being shown read-only on the Destination Metadata page. Its includeInNotes flag can still be set even though its content cannot be customised per destination.

includeInNotes is optional and, like metadata, follows this endpoint's full-replace semantics: a field name absent from it is saved with the flag off, so a GET → edit → PUT round trip must resend includeInNotes exactly as returned by the GET if you want to preserve it — omitting it entirely clears every field's flag for that destination.

Path parameters:

Request body: Content-Type: application/json

{
  "metadata": {
    "General": {
      "organisationWebPage": "https://www.example.org/",
      "generalComments": "Updated via REST API"
    },
    "Contacts": {
      "computerOperations": [
        { "name": "Alice Smith", "email": "alice@example.org", "phone": "+44 1234 567890" },
        { "name": "Bob Jones",   "email": "bob@example.org" }
      ],
      "mailGroup": { "name": "ops-list", "email": "ops@example.org" }
    },
    "Documentation": {
      "opsviewNotes": "# Operational Notes\n\n- Maintenance window: Sundays 02:00-04:00 UTC"
    }
  },
  "includeInNotes": {
    "Documentation": { "opsviewNotes": true }
  }
}

Service name: setDestinationMetaValues

Response:

{
  "success": "yes",
  "destination": "hourly_aq",
  "count": 3
}

Destination Backups¶

Destination backup operations allow exporting and restoring destination configurations.

GET /v1/destination/backup¶

Returns backup data for a set of destinations, optionally filtered.

Query parameters:

Service name: destinationBackupList

Each host's passwd field is included only if the client also has the showSensitiveInfo permission (see Sensitive Fields) — omitted otherwise.

GET /v1/destination/backup/{name}¶

Returns backup data for a single destination.

Path parameters:

Service name: destinationBackupList

Same showSensitiveInfo behaviour for host passwords as above.

PUT /v1/destination/backup¶

Restores one or more destinations from a backup JSON structure.

Query parameters:

Request body: Content-Type: application/json

{
  "backup": { ... }
}

Service name: putDestinationBackup

Response:

{
  "status": "ok",
  "message": "Number of Destination(s) created: 3"
}

Hosts¶

POST /v1/host/option¶

Sets a configuration option on a host. The name parameter uses dot-notation <module>.<key>.

Query parameters:

Form body: Content-Type: application/x-www-form-urlencoded

Service name: updateHostOption

Response:

{ "status": "ok" }

Monitoring¶

GET /v1/monitoring/summary¶

Returns the merged step-status list for every product and cycle currently known (the same data shown in the web interface's "All Cycles and Products" view at /do/monitoring/summary/), optionally narrowed down with the query filters below.

Query parameters:

Service name: monitoringSummaryList

Response:

{
  "status": "ok",
  "stepStatusList": [
    {
      "product": "DisseminationProducts", "time": "00", "buffer": 0, "step": 0, "type": "FC",
      "status": "Done", "statusCode": "DONE", "statusLevel": 1,
      "arrivalTime": 1732012345, "scheduledTime": 1732012000, "lastUpdate": 1732012345,
      "productTime": 1731984000, "minutesBeforeSchedule": 5
    },
    ...
  ]
}

GET /v1/monitoring/summary/{product}¶

Returns the merged step-status list for every cycle currently known for one product (the same data shown in the web interface's "All Cycles" view at /do/monitoring/summary/{product}), optionally narrowed down with the query filters below.

Path parameters:

Query parameters:

Service name: monitoringSummaryList

Response: same shape as GET /v1/monitoring/summary above.

GET /v1/monitoring/summary/{product}/{time}¶

Returns the current monitoring step-status summary for a given product and reference time, optionally narrowed down with the query filters below.

Path parameters:

Query parameters:

Service name: monitoringSummaryList

Response:

{
  "status": "ok",
  "stepStatusList": [
    { "step": 0, "type": "FC", "status": "done", ... },
    ...
  ]
}

GET /v1/monitoring/summary/{product}/{time}/{step}/{type}¶

Returns the historical status list for a specific product step.

Path parameters:

Service name: monitoringSummaryList

Response:

{
  "status": "ok",
  "stepStatusHistoryList": [ ... ]
}

Data Files¶

GET /v1/datafile/put¶

Registers a new data file for dissemination to a destination. The file must already be accessible at the given source URL or path.

Query parameters:

Service name: datafilePut

Response:

{
  "status": "ok",
  "id": 123456
}

The returned id is the internal data file identifier, usable with datafileSize and datafileDel.

GET /v1/datafile/size¶

Returns the size (in bytes) of a data file by its internal ID.

Query parameters:

Service name: datafileSize

Response:

{
  "status": "ok",
  "size": 1048576
}

DELETE /v1/datafile/del¶

Deletes a data file from the system by its internal ID.

Query parameters:

Service name: datafileDel

Response:

{ "status": "ok" }

Error Reference¶

Complete Configuration Example¶

The following shows a typical [API] section for a production configuration with multiple API users:

[API]
# Full administrative access
admin_api=Admin$ecret99:.*

# Read-only metadata access
metadata_reader=MdRead42:getDestinationMetaFields|getDestinationMetaValuesByDestination

# Pipeline user: submit and delete files, read destination info
pipeline=Pipe#pass88:datafilePut|datafileDel|datafileSize|destinationList|destination

# Incoming user management (e.g. called from a provisioning system)
provisioning=Prov&key77:incomingUser.*|incomingCategory.*|incomingAssociation.*

Related¶

• OpenECPDS Entities
• Product Descriptions
• Data Ownership & Catalogue
• Monitoring