Understanding Sites URLs¶

ECMWF Sites uses one host for the Hub and for all sites. The path after the host selects the part of the platform that answers the request. This guide lists every URL path family, explains when to use each one, and shows a complete example.

The examples use these values:

Your host depends on the environment. The Hub shows the exact URL for each page, file, token, and interface it offers. When in doubt, copy the URL from the Hub instead of building it yourself.

URL anatomy¶

A Sites URL has this structure:

https://<host>/<space>/<site>/<content>/s/<service>/…
│          │             │        │      │
│          │             │        │      └─ Platform service: API, sharing, interfaces
│          │             │        └──────── Your files and folders, or a custom application
│          │             └───────────────── Site name
│          └─────────────────────────────── Space, or the owner name
└────────────────────────────────────────── Platform host (scheme + domain)

• Host: the platform address. It is the same for the Hub and for all sites.
• Space: the first path segment of a site URL. If the site has no space, the owner's username appears instead. See Site settings for how to set the space and name.
• Site name: the second path segment.
• Site path: /<space>/<site>/. The site owns every path below it.
• s/ service paths: the platform uses the s segment directly under the site path for its own services: s/api/, s/admin/, s/dav/, s/s3/, s/signed/, s/session/, s/_m2m/, and s/healthz. The platform answers requests for these paths before your content. To stay clear of them, do not create a top-level folder named s.

Hub pages¶

The Hub is the web portal where you create and manage sites. You use these paths in a browser, after you log in.

Example: the overview page of the sample site is https://sites.example.org/hub/view/forecast-lab/radar-viewer/.

Use Hub pages to manage a site by hand. Use the Hub API to manage sites from a script.

Hub API¶

The Hub API manages the sites themselves: creation, configuration, restart, tokens, and sharing links. A site's own content is not in the Hub API; it is in the Site API.

Site operations live under /hub/api/v2/sites/<space>/<site>/. Examples:

# Get the status of one site
curl -H "Authorization: Bearer ${HUB_TOKEN}" \
  "https://sites.example.org/hub/api/v2/sites/forecast-lab/radar-viewer/status/"

# Restart the site
curl -X POST -H "Authorization: Bearer ${HUB_TOKEN}" \
  "https://sites.example.org/hub/api/v2/sites/forecast-lab/radar-viewer/restart/"

Use the Hub API when you automate site management: for example, a pipeline that creates a site for every project. For the token types the Hub API accepts, see Managing access.

Site content paths¶

Every path under the site prefix that is not an s/ service path is your site content. The site proxy serves the files and folder listings you publish.

• Use content paths for what people open, bookmark, and embed: pages, images, and downloads.
• On a public site, anyone can use content paths without a login.
• On a private site, a browser must log in first. For scripts, use the Site API or the token-based paths below.
• The download-folder path answers GET, HEAD, and OPTIONS only. The folder listing page offers it as the Download folder action.

Site API paths¶

The Site API reads and writes the content of one site. Build every Site API URL from the site path:

https://sites.example.org/forecast-lab/radar-viewer/s/api/v2/…

Authenticated requests need a credential: an HTTP access token, the site master token, or a site administrator login in a browser. Send it as a Bearer token:

# Upload a file
curl -X PUT -H "Authorization: Bearer ${SITE_TOKEN}" \
  --data-binary @summary.pdf \
  "https://sites.example.org/forecast-lab/radar-viewer/s/api/v2/files/reports/summary.pdf"

# List a folder as JSON
curl -H "Authorization: Bearer ${SITE_TOKEN}" \
  "https://sites.example.org/forecast-lab/radar-viewer/s/api/v2/files/reports/?list=true"

Use /s/api/v2/pub/ instead of /s/api/v2/ for anonymous reads on a public site. The public endpoint has no write handlers; other methods answer 404 Not Found.

/s/api/v1/ answers the old file operations for compatibility. Use v2 for new work.

The Site API cookbook shows full recipes. The Open API URL in the site's overview page shows the complete reference for your site.

Sharing URLs: signed URLs and session URLs¶

A sharing URL carries its own permission. The recipient needs no site access and no login until the URL expires. Both types start from the site path:

• A signed URL with permission r answers only the read methods: GET, HEAD, OPTIONS, PROPFIND, and SEARCH. Use rw when the recipient must change the resource.
• A session URL carries its token in the path, not in a header. Requests with a read method open the file browser at the scoped path; write methods go to the session-files API behind it.
• Both URLs are credentials. Anyone who sees one can use it until it expires. Do not put them in public pages or logs.

Create both types in the Hub (the Sharing tab of the site overview) or with an API call. Signed and session URLs for safe sharing explains when to choose each type and shows the requests.

Machine-to-machine content access¶

On a private site, every content path sits behind the ECMWF login: the platform redirects a request without a session to the sign-in page. A browser completes that flow; a script cannot. The s/_m2m/ prefix exists for machine-to-machine communication: the platform exempts these paths from the login redirect, and the site authenticates the request with a token.

Build the URL from any path the site serves, with s/_m2m/ inserted after the site path:

https://sites.example.org/forecast-lab/radar-viewer/s/_m2m/reports/summary.pdf

Send one of these credentials in the Authorization header, as in the Site API examples:

curl -H "Authorization: Bearer ${SITE_TOKEN}" \
  -o summary.pdf \
  "https://sites.example.org/forecast-lab/radar-viewer/s/_m2m/reports/summary.pdf"

The same call works with other methods against a custom application. For example, a pipeline that triggers a rebuild endpoint of the site's application:

curl -X POST -H "Authorization: Bearer ${SITE_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"run": 42}' \
  "https://sites.example.org/forecast-lab/radar-viewer/s/_m2m/api/frames/rebuild"

How the site answers these requests:

• The platform removes the _m2m segment, then applies the normal access rules of the private site. The request then behaves exactly like the plain path behaves for a signed-in user: a file download or a folder listing on a file site, or a request forwarded with its original method to a custom application.
• A missing, invalid, or expired token answers 403 with a JSON body. The request never goes through a login redirect, so a script gets a clean error.
• The prefix exists on private sites only. Public content needs no token: use the plain content path.

How s/_m2m/ differs from the other token paths:

• s/_m2m/ reaches the site's own paths: the content files and folder listings of a file site, and every route of a custom application, with any HTTP method. Use it when a service holds a site URL and a token, for example a pipeline that reads URLs recorded in a manifest, or a job that calls an endpoint of another site's application.
• The Site API /s/api/v2/… does not cover those needs. It manages content only: JSON listings, upload, delete, and archives. It has no handlers for your application routes, and it does not serve the plain content URLs.
• The other s/ services do not need _m2m. The Site API, WebDAV, S3, and the sharing URLs already accept tokens or capabilities without a login redirect.
• Use a signed URL when the recipient has no account and no token.

Site application interfaces¶

These paths appear only when a site administrator enables the application. When enabled, the site's overview page shows the exact URL.

See WebDAV and S3 for the authentication each interface needs.

Custom application paths¶

A site can run your own container image instead of the file platform. The image must accept connections on port 8000, on all network interfaces (0.0.0.0). Visitors use the full site URL, for example https://sites.example.org/forecast-lab/radar-viewer/api/frames/latest. Your application defines what the path after the site path means; the platform does not give it a fixed shape.

What your application answers. When the custom application is active, the proxy forwards the requests under the site path to your application. Only the services this guide documents keep their own routes: the s/ service paths and the download-folder ZIP shortcut. The platform does not serve the file listing or the content files themselves in this mode. The site volume is mounted in your container under /www, so your application can read and write the same content, and serve it, when your application is written to do that. The site access rules apply before your application sees a request, and the platform adds the retention banner to the HTML responses.

The URL path setting decides which path your application receives for the example URL:

• A signed URL or session URL request passes the platform verification first, then reaches your application as a normal path request, without the sharing prefix.
• In FastCGI mode the platform always sends the full request path to the application.

A public site answers read-only methods only: GET, HEAD, OPTIONS, PROPFIND, and SEARCH. Your application receives no POST on a public site; the platform answers 403 first. When your application can put its input in the URL, use GET. Use a private site for an application that needs a request body.

See Custom applications for the proxy mode, the full setup, and environment variables.

Which URL do I need?¶

Platform-only paths¶

These paths exist for the operation of the platform. Do not link to them:

• /<space>/<site>/s/healthz: the proxy health location. It answers the site's own loopback probe and trusted platform IP addresses only.
• /s/metrics: Prometheus metrics. Note that this path is not under the site path. The platform scraper reaches it with a trusted client address only.
• /hub/error/page/<code>/: the shared error pages the platform shows for site errors.
• /favicon.ico and /favicon.svg: the platform icon of the installation.
• Legacy root paths without the /hub prefix, such as /list/, /view/<space>/<site>/, and /error/page/<code>/. They redirect to their /hub/… equivalents. Use the /hub forms.

For the full technical description of every path, see the Endpoint anatomy section of the routing and architecture overview.