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

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 are defined in the OpenECPDS properties file under the [API] section. 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.*

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/{product}/{time}¶

Returns the current monitoring step-status summary for a given product and reference time.

Path parameters:

Service name: (basic auth only)

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: (basic auth only)

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