REST API Reference
The Repository module exposes a REST API for programmatic access to repository content. This enables external systems, ETL pipelines, and custom scripts to query files stored in the repository without navigating the UI.
Overview
Base URL: repository/api/v1
Authentication: All endpoints require an Authentication header containing a valid API token. Responses are filtered by the access rights of the authenticated user — files the caller cannot read are silently excluded from results.
Content-Type: application/json
Endpoints
| Method | Path | Summary |
|---|---|---|
GET |
repository/api/v1/list-files |
List files whose filename ends with the given extension |
Endpoint Reference
GET repository/api/v1/list-files
Summary: Returns all file paths in the repository whose filename ends with the specified extension, limited to files the authenticated user has read access to.
Authentication: Requires a valid API token in the Authentication header. Results are automatically filtered to files the caller can read. A user with the mod-repository-admin privilege receives all matching files across the entire repository.
Path parameters: none
Query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
extension |
string | Yes | The file extension to search for, with or without a leading dot (e.g. rml or .rml). |
Request body: none
Response — 200 OK:
A JSON array of file path strings.
[
"/AGC/OldDS/2020-06-13/Report/AGC_Logo.rml",
"/AGC/OldDS/2020-06-13/Report/CIVIL.rml",
"/AGC/OldDS/2020-06-13/Report/CRIME.rml"
]
Response fields:
| Field | Type | Description |
|---|---|---|
| (root) | string array | Matched file paths. Empty array [] when no matching files are found. |
Error responses:
| Status | Condition |
|---|---|
400 Bad Request |
extension parameter is missing or blank |
401 Unauthorized |
Missing or invalid API token |
Note: The endpoint always returns HTTP 200 when the extension is valid — it does not return 404 when the extension has no matches. An empty array indicates no results.
Example requests:
# Find all RML report files
curl -H "Authentication: elx.token YOUR_TOKEN" \
"https://example.com/repository/api/v1/list-files?extension=rml"
# Find all datasource files
curl -H "Authentication: elx.token YOUR_TOKEN" \
"https://example.com/repository/api/v1/list-files?extension=ds"
# Find all Word documents
curl -H "Authentication: elx.token YOUR_TOKEN" \
"https://example.com/repository/api/v1/list-files?extension=docx"
# Leading dot is accepted and stripped automatically
curl -H "Authentication: elx.token YOUR_TOKEN" \
"https://example.com/repository/api/v1/list-files?extension=.xlsx"
Matching Algorithm
The API matches files where the filename ends with .<extension>. This has a few important consequences:
Multiple extensions: A file named data.csv.xlsx matches both extension=xlsx and extension=csv.xlsx, but does not match extension=csv because the filename does not end with .csv.
Dotfiles: A file named .gitignore matches extension=gitignore because the filename ends with .gitignore.
Leading dot: Supplying a leading dot is allowed — extension=.rml is treated identically to extension=rml.
Limitations
Extensionless files cannot be found. Files with no extension (such as README or Makefile) cannot be retrieved via this endpoint. The underlying mechanism requires a dot-separated extension to match against.
Availability
This endpoint is available in:
| Product | Module | Minimum Version |
|---|---|---|
| Ambience | repository | 8.3.12 |
| Repertoire | repository-disk | 8.3.8 |