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.

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

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"]
}

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.

GET /v1/destination/metadata/fields¶

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

Parameters: none

Service name: getDestinationMetaFields

Response:

{
  "status": "ok",
  "fields": [
    {
      "id": 1,
      "name": "organisationWebPage",
      "label": "Organisation Web Page",
      "type": "url",
      "category": "General",
      "active": true
    },
    {
      "id": 8,
      "name": "computerOperations",
      "label": "Computer Operations",
      "type": "contact",
      "category": "Contacts",
      "active": true
    },
    ...
  ]
}

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.

Path parameters:

Service name: getDestinationMetaValuesByDestination

Response:

{
  "status": "ok",
  "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/"
    }
  }
}

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.

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" }
    }
  }
}

Service name: setDestinationMetaValues

Response:

{
  "status": "ok",
  "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

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

Returns backup data for a single destination.

Path parameters:

Service name: destinationBackupList

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