> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Files & Artifacts API Reference

> Reference Starfire AI file upload/metadata concepts and durable artifact listing, metadata, download, ownership, and retention behavior.

# Files & artifacts API reference

Files are reusable inputs or stored resources. Artifacts are durable workflow outputs. Treating them as separate resource types keeps long-running jobs small and supportable.

## File resource

The Alpha v1 architecture includes a file resource family for supported uploads and metadata.

A file can be associated with:

* a Project
* Knowledge ingestion
* a Research input
* a FORGE build input
* another supported workflow

Uploading a file does not automatically mean the source is indexed into Knowledge.

## Artifact resource

Artifacts can expose operations for listing authorized outputs, reading metadata, downloading packaged content, and deleting/expiring an artifact when permitted.

Useful metadata includes:

* artifact ID
* owning user/organization/project
* source build/run
* name/type
* size
* file count
* checksum
* created/expiration time
* status

## Downloads

Use the documented Starfire download flow. Do not build against internal storage object paths or temporary signed URLs as permanent identifiers.

## Checksums

A checksum lets your application verify that downloaded bytes match the packaged artifact. It does not certify the software inside as safe or correct.

## Retention

Files and artifacts can have different retention policies. A developer integration should not assume indefinite storage unless the active product contract explicitly provides it.

## Authorization

Possession of an artifact ID does not grant download permission. Starfire still checks the credential, owning context, and resource permissions.

<Warning>
  Never expose a private Starfire file or artifact through your own public application without making an explicit authorization decision in that application.
</Warning>