Backend REST API

REST and streaming endpoints implemented by matyan-backend. All routes are under /api/v1/rest (or as configured). The following sections list the endpoint handler functions generated from the Python API modules.

Runs (CRUD and logs)

Run lifecycle, metadata, tags, notes, logs, and artifact download.

matyan_backend.api.runs._run

Run API endpoints — non-streaming CRUD operations.

Streaming search endpoints (run search, metric search, etc.) live in _streaming.py and are registered on the same rest_router_runs router.

add_tag_to_run_api(run_id, body, db) async

Add a tag to a run (create tag if it does not exist).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
body	StructuredRunAddTagIn	Must include tag_name.	required

Returns:

Type	Description
dict[str, str]	{"id": run_id, "tag_id": tag_id, "status": "OK"}.

Raises:

Type	Description
HTTPException	404 if run not found.

archive_runs_batch_api(body, db, producer, archive=True) async

Archive or unarchive multiple runs; emit control events for each.

Parameters:

Name	Type	Description	Default
body	RunsBatchIn	List of run hashes.	required
archive	bool	True to archive, False to unarchive.	True

Returns:

Type	Description
dict[str, str]	{"status": "OK"}.

clear_run_tombstone_api(run_id, db) async

Clear the tombstone for a run (e.g. after undo delete).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required

create_run_note_api(run_id, note_in, db) async

Create a note attached to a run.

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
note_in	NoteIn	Body with content.	required

Returns:

Type	Description
dict[str, Any]	{"id": note_id, "created_at": ...}.

delete_run_api(run_id, db, ingestion_producer) async

Mark run as deleted in FDB and emit control event for async cleanup (e.g. S3).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required

Returns:

Type	Description
dict[str, str]	{"id": run_id, "status": "OK"}.

Raises:

Type	Description
HTTPException	404 if run not found.

delete_run_note_api(run_id, _id, db) async

Delete a note (must belong to the run).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
_id	str	Note ID.	required

Returns:

Type	Description
dict[str, str]	{"status": "OK"}.

Raises:

Type	Description
HTTPException	404 if note not found or not owned by run.

delete_runs_batch_api(body, db, ingestion_producer) async

Mark multiple runs as deleted and emit control events for each.

Parameters:

Name	Type	Description	Default
body	RunsBatchIn	List of run hashes to delete.	required

Returns:

Type	Description
dict[str, str]	{"status": "OK"}.

download_all_artifacts_api(run_id, db) async

Stream all run artifacts as a ZIP archive.

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required

Returns:

Type	Description
StreamingResponse	StreamingResponse (application/zip).

Raises:

Type	Description
HTTPException	404 if run not found or has no artifacts.

download_artifact_api(run_id, db, path) async

Download a single artifact file by path (S3 blob streamed to client).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
path	Annotated[str, Query()]	Artifact path/name within the run.	required

Returns:

Type	Description
Response	Raw response with file content and Content-Disposition.

Raises:

Type	Description
HTTPException	404 if run or artifact not found.

finish_runs_batch_api(body, db) async

Mark multiple runs as finalized (active=False, set finalized_at).

Parameters:

Name	Type	Description	Default
body	RunsBatchIn	List of run hashes to finish.	required

Returns:

Type	Description
dict[str, str]	{"status": "OK"}.

get_run_info_api(run_id, db, skip_system=False, sequence=()) async

Return run info: params, traces overview, props, and artifacts list.

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
skip_system	bool	If True, omit __system_params from params.	False
sequence	Annotated[tuple[str, ...], Query()]	Limit traces to these sequence types; empty means all.	()

Returns:

Type	Description
dict	Dict with params, traces, props, artifacts.

Raises:

Type	Description
HTTPException	404 if run not found.

get_run_log_records_api(run_id, db, record_range='') async

Stream structured log records for a run (binary Aim codec).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
record_range	str	Optional start:stop range (default: last 200).	''

Returns:

Type	Description
StreamingResponse	StreamingResponse (application/octet-stream); total count in header.

get_run_logs_api(run_id, db, record_range='') async

Stream terminal log lines for a run (binary Aim codec).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
record_range	str	Optional start:stop range (default: last 200 lines).	''

Returns:

Type	Description
StreamingResponse	StreamingResponse (application/octet-stream).

get_run_note_api(run_id, _id, db) async

Get a single note by ID (must belong to the run).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
_id	str	Note ID.	required

Returns:

Type	Description
dict[str, Any]	{"id", "content", "updated_at"}.

Raises:

Type	Description
HTTPException	404 if note not found or not owned by run.

list_run_notes_api(run_id, db) async

List all notes for a run.

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required

Returns:

Type	Description
list[dict]	List of note dicts (id, content, created_at, updated_at, etc.).

remove_tag_from_run_api(run_id, tag_id, db) async

Remove a tag association from a run.

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
tag_id	str	Tag ID to remove.	required

Returns:

Type	Description
dict[str, Any]	{"id": run_id, "removed": True, "status": "OK"}.

Raises:

Type	Description
HTTPException	404 if run not found.

update_run_api(run_id, body, db, producer) async

Update run properties (name, description, archived, active, experiment).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
body	StructuredRunUpdateIn	Fields to update (only provided fields are changed).	required

Returns:

Type	Description
dict[str, str]	{"id": run_id, "status": "OK"}.

Raises:

Type	Description
HTTPException	404 if run not found.

update_run_note_api(run_id, _id, note_in, db) async

Update a note's content (note must belong to the run).

Parameters:

Name	Type	Description	Default
run_id	str	Run hash.	required
_id	str	Note ID.	required
note_in	NoteIn	Body with content.	required

Returns:

Type	Description
dict[str, Any]	{"id", "content", "updated_at"}.

Raises:

Type	Description
HTTPException	404 if note not found or not owned by run.

Runs (streaming search)

Run search, metric search, active runs, metric alignment, and metric batch. These endpoints use the binary streaming codec.

matyan_backend.api.runs._streaming

Streaming search endpoints for runs and metrics.

All endpoints return StreamingResponse using the binary codec from api.streaming which the Aim UI understands.

SortSpec dataclass

A single sort key: field name + direction.

run_search_api(db, q='', limit=0, offset='', sort='', skip_system=True, report_progress=True, exclude_params=False, exclude_traces=False, x_timezone_offset=Header(default=0)) async

Search runs with optional multi-key sorting.

Parameters:

Name	Type	Description	Default
sort	str	JSON-encoded sort specification, e.g. '[{"field":"run","order":"asc"},{"field":"date","order":"desc"}]'. Supported fields: run, experiment, hash, date, duration, description, creator. Defaults to [{"field":"date","order":"desc"}].	''

Experiments

Experiment CRUD, runs listing, notes, and activity.

matyan_backend.api.experiments._main

Experiment REST endpoints: CRUD, runs listing, notes, and activity.

All routes are under the /experiments prefix on :data:rest_router_experiments.

create_experiment_api(request, db) async

Create a new experiment by name.

Raises:

Type	Description
HTTPException	400 if name is duplicate or invalid.

create_note_api(exp_id, note_in, db) async

Create a note attached to an experiment.

Raises:

Type	Description
HTTPException	404 if experiment not found.

delete_experiment_api(uuid, db, producer) async

Delete an experiment and emit control event for async side effects.

Raises:

Type	Description
HTTPException	404 if not found.

delete_note_api(exp_id, _id, db) async

Delete a note.

Raises:

Type	Description
HTTPException	404 if note not found.

experiment_runs_activity_api(exp_id, db, x_timezone_offset=0) async

Return experiment activity (run counts, activity map by day).

Parameters:

Name	Type	Description	Default
exp_id	str	Experiment UUID.	required
x_timezone_offset	Annotated[int, Header()]	Timezone offset in minutes (header).	0

Raises:

Type	Description
HTTPException	404 if experiment not found.

get_experiment_api(uuid, db) async

Get a single experiment by UUID.

Raises:

Type	Description
HTTPException	404 if not found.

get_experiment_runs_api(uuid, db, limit=None, offset=None) async

List runs belonging to the experiment (with optional limit/offset).

Raises:

Type	Description
HTTPException	404 if experiment not found.

get_experiments_list_api(db) async

List all experiments.

get_note_api(exp_id, _id, db) async

Get a single note by ID.

Raises:

Type	Description
HTTPException	404 if note not found.

list_note_api(exp_id, db) async

List all notes for an experiment.

Raises:

Type	Description
HTTPException	404 if experiment not found.

search_experiments_by_name_api(db, q=None) async

Search experiments by name (case-insensitive substring).

update_experiment_properties_api(uuid, exp_in, db) async

Update experiment name, description, or archived state.

Raises:

Type	Description
HTTPException	404 if experiment not found.

update_note_api(exp_id, _id, note_in, db) async

Update a note's content.

Raises:

Type	Description
HTTPException	404 if note not found.

Tags

Tag CRUD and tagged runs listing.

matyan_backend.api.tags._main

Tag REST endpoints: CRUD and tagged runs listing.

All routes are under the /tags prefix on :data:tags_router.

create_tag_api(tag_in, db) async

Create a new tag (name, optional color and description).

Raises:

Type	Description
HTTPException	400 if name is duplicate or invalid.

delete_tag_api(tag_id, db, producer) async

Delete a tag and emit control event for async side effects.

Raises:

Type	Description
HTTPException	404 if tag not found.

get_tag_api(tag_id, db) async

Get a single tag by ID.

Raises:

Type	Description
HTTPException	404 if not found.

get_tagged_runs_api(tag_id, db) async

List runs that have the given tag (with run_id, name, experiment, times).

Raises:

Type	Description
HTTPException	404 if tag not found.

get_tags_list_api(db) async

List all tags.

search_tags_by_name_api(db, q='') async

Search tags by name (case-insensitive substring).

update_tag_properties_api(tag_id, tag_in, db) async

Update tag name, color, description, or archived state.

Raises:

Type	Description
HTTPException	404 if tag not found.

Projects

Project info, activity, params aggregation, and pinned sequences.

matyan_backend.api.projects._main

Project REST endpoints: info, activity, params aggregation, pinned sequences.

All routes are under the /projects prefix on :data:rest_router_projects.

get_pinned_sequences_api(db) async

Return the list of pinned sequences for the project.

get_project_activity_api(db, x_timezone_offset=0) async

Return project activity (e.g. run counts over time); uses timezone offset header.

get_project_api(db) async

Return project-level info (name, path, etc.).

get_project_params_api(db, sequence=(), exclude_params=False) async

Return aggregated params (and optionally sequence info) across runs.

get_project_status_api() async

Return project status (always up-to-date for this backend).

update_pinned_sequences_api(body, db) async

Update the list of pinned sequences.

Dashboards

matyan_backend.api.dashboards.views

Dashboard REST endpoints: CRUD for dashboards (mounted under /rest/dashboards).

create_dashboard_api(body, db) async

Create a new dashboard (name, optional description and app_id).

delete_dashboard_api(dashboard_id, db) async

Archive a dashboard (soft delete).

Raises:

Type	Description
HTTPException	404 if not found.

get_dashboard_api(dashboard_id, db) async

Get a single dashboard by ID.

Raises:

Type	Description
HTTPException	404 if not found.

get_dashboards_api(db) async

List all non-archived dashboards.

update_dashboard_api(dashboard_id, body, db) async

Update dashboard name and/or description.

Raises:

Type	Description
HTTPException	404 if not found.

Dashboard apps

matyan_backend.api.dashboard_apps.views

Dashboard apps (explore state) REST endpoints: CRUD (mounted under /rest/apps).

create_app_api(body, db) async

Create a new dashboard app (type and optional state).

delete_app_api(app_id, db) async

Delete a dashboard app.

Raises:

Type	Description
HTTPException	404 if not found.

get_app_api(app_id, db) async

Get a single dashboard app by ID.

Raises:

Type	Description
HTTPException	404 if not found.

get_apps_api(db) async

List all dashboard apps (explore states).

update_app_api(app_id, body, db) async

Update dashboard app type and/or state.

Raises:

Type	Description
HTTPException	404 if not found.

Reports

matyan_backend.api.reports.views

Report REST endpoints: CRUD for reports (mounted under /rest/reports).

create_report_api(body, db) async

Create a new report (name, optional code and description).

delete_report_api(report_id, db) async

Delete a report.

Raises:

Type	Description
HTTPException	404 if not found.

get_report_api(report_id, db) async

Get a single report by ID.

Raises:

Type	Description
HTTPException	404 if not found.

get_reports_api(db) async

List all reports.

update_report_api(report_id, body, db) async

Update report name, code, and/or description.

Raises:

Type	Description
HTTPException	404 if not found.