Skip to main content

Overview

Introduction​

Working with a Project involves creating Artifacts. Artifacts include Models, Data, Dashboards, and arbitrary Files. Artifacts can be created by a Workflow or manually uploaded. Organizationally, Artifacts within a Project behave much like a file system in that:

  1. they are located within a Folder and
  2. have a unique name within their Folder for their Artifact type.
info

Folders act as namespaces to separate Artifacts with the same name and Artifact type.

Version-Controlled Resources​

Sedaro Artifacts use the platform's native version control. A logical Artifact has a stable id, while each concrete revision has its own unique version ID. Concrete versions are immutable: changing an Artifact, including moving it to another Folder, creates a new version rather than overwriting an existing one.

The version visible as an Artifact's active state is selected by a Branch or Checkpoint. Writing to a Branch advances that Branch's open Checkpoint; another Branch or Checkpoint may continue to select an earlier version. There is therefore no single platform-wide "current" or "latest" version for an Artifact. See Version Control for the Workspace, Branch, and Checkpoint model.

Referencing Artifacts​

Artifact APIs address a logical Artifact by its stable id. The concrete version returned by a read is selected with the optional ref query parameter:

  • omit ref to use the Workspace's default Branch
  • provide a Branch name to read or write that Branch's selected state
  • provide a Checkpoint ID to read an immutable Workspace snapshot
  • provide an exact concrete version ID to read one immutable Artifact version

For example, a File is addressed as /api/artifacts/v1/files/{id}/?ref=branch-name, and a Series Data stream is addressed as /api/artifacts/v1/series/{id}/streams/{stream}?ref=version-id. Create, update, and delete metadata operations must resolve to a writable Branch; Checkpoint and exact-version refs are read-only. Series Data remote ingestion is a special existing-version blob-write path and does not create or update metadata or advance a Branch; see Uploading Series Data.

Where an endpoint supports lookup by Folder and name, that lookup is also evaluated in the selected Branch or Checkpoint. Folder organization is versioned, so the same path can resolve to different state on different refs.

API responses expose the selected logical id and concrete version. Neither alias represents a separate global current version.

Deprecated

The legacy version query parameter is still accepted as an alias for ref, but new clients should use ref. Some responses may also include the deprecated artifact alias for id and currentVersion alias for version for compatibility.

Artifacts are discoverable by querying for Artifacts in a selected Folder and ref. To enumerate a subtree, first obtain the Folder tree for that ref and query each Folder; Artifact list endpoints return the selected Folder's direct contents rather than flattening its sub-Folders.

Artifact Deletion​

Deleting a versioned Artifact is a Branch-scoped change. It removes the Artifact from the selected Branch's live state while preserving the Artifact's prior versions and history.

caution

A deleted Artifact is omitted from ordinary reads and listings for that Branch.

  • Earlier versions remain available through an exact version ref and remain part of version history.
  • Deleting a Folder also removes the resources contained in its selected Branch state; their prior versions remain in history.
  • Individual concrete versions cannot be deleted independently through the Artifact API.
  • Creating an Artifact with the same name in the Folder later creates a new logical Artifact with a new id.
warning

Artifact deletion changes the selected Branch state; it is not a history purge. Historical versions remain readable, and Branch or Checkpoint operations can select prior state.

Types of Artifacts​

Sedaro supports multiple types of Artifacts, each optimized for different use cases and data formats. All Artifact types share common characteristics and organizational principles while providing specialized functionality for their respective data types.

Shared Characteristics​

All Artifacts, regardless of type, include these fundamental properties:

  • Name: A descriptive identifier for the Artifact within its Folder namespace
  • Content Type: A user-defined categorization field for organizing and filtering Artifacts by purpose or domain
  • Discoverability: Controls whether the Artifact appears in standard listings (searchable) or is excluded by default (unlisted) while remaining accessible via direct reference
  • Logical ID: A stable identifier shared by every concrete version of the Artifact
  • Version ID: A unique identifier for one immutable concrete version
  • Selected State: The version selected by the requested Branch or Checkpoint
  • Version History: The lineage of concrete versions, which can be inspected and selected without overwriting earlier versions
info

The different Artifact types have specialized APIs and capabilities while maintaining consistent versioning and folder organization principles.

File Artifacts​

File Artifacts represent traditional file-based content such as documents, images, configuration files, and other binary or text data. Key characteristics include:

  • Content Storage: Files are stored with their original content and can be downloaded in their native format
  • MIME Type Detection: File types are automatically detected if not explicitly set and stored to help with proper content handling
  • Priority System: Files can be assigned priority levels (0-10) to indicate their relative importance within a project
  • Size Tracking: File sizes are tracked and reported for storage management
  • Format Flexibility: Supports any file format, from simple text files to complex binary formats

File Artifacts are ideal for storing documentation, configuration files, images, reports, and any other traditional file-based content that needs to be version controlled and shared across team members.

info

In Sedaro Cloud, File Artifacts are scanned and monitored via state-of-the-art malware detection systems as part of Sedaro's multi-layer defense-in-depth cybersecurity strategy.

Series Data Artifacts​

Series Data Artifacts are specialized containers for time-series data, particularly suited for modeling and simulation data. Key characteristics include:

  • Time Boundaries: Data is bounded by start and stop times using Modified Julian Date (MJD) format for precise temporal representation
  • Stream Organization: Data is organized into multiple streams, each representing different measurement channels or data sources
  • Streaming Access: Supports efficient streaming access to large datasets without requiring full downloads
  • Sample Rate Management: Handles multiple sample rates and provides automatic rate adjustment for data retrieval
  • Simulation Integration: Designed specifically for simulation output data with built-in analysis and description capabilities

Series Data Artifacts are optimized for handling large-scale simulation results, telemetry data, and other time-indexed datasets where efficient querying and streaming access are essential.

Additional documentation is also available, providing much more in-depth description of Series Data Artifacts, and information on how to work with Series Data.