Skip to main content
pragma-os provides a built-in pragma/file resource for uploading and managing files. Files are stored in platform storage and expose download URLs that other resources can reference.

​
Prerequisites

  • pragma CLI installed and authenticated (pragma auth login)

​
Using the CLI

​
Upload with @path syntax

The simplest way to upload a file is using the @path syntax in your YAML config: 
provider: pragma
resource: file
name: training-data
config:
  content: "@./data/training-set.jsonl"
  content_type: "application/jsonl"

pragma resources apply training-data.yaml
The CLI:
  1. Reads the file from the local path (relative to the YAML file’s directory)
  2. Uploads the file content to pragma-os storage
  3. Creates the pragma/file resource to track it

​
File Outputs

After the file resource reaches ready state, it exposes these outputs:
OutputDescription
urlInternal storage URL
public_urlPublic download URL
sizeFile size in bytes
content_typeMIME type
checksumContent checksum for integrity verification
uploaded_atUpload timestamp
View the outputs: 
pragma resources describe pragma/file training-data

​
Using the SDK

​
Upload programmatically

from pragma_sdk import PragmaClient

with PragmaClient() as client:
    # Upload the file content
    with open("training-data.jsonl", "rb") as f:
        result = client.upload_file(
            name="training-data",
            content=f.read(),
            content_type="application/jsonl",
        )

    print(f"Uploaded: {result['public_url']}")

    # Create the file resource to track it
    client.apply_resource({
        "provider": "pragma",
        "resource": "file",
        "name": "training-data",
        "lifecycle_state": "pending",
        "config": {
            "content_type": "application/jsonl",
        },
    })

​
Referencing Files from Other Resources

File outputs can be referenced by other resources using FieldReferences. For example, to use an uploaded document as a knowledge source for an AI agent: 
# Upload the document
provider: pragma
resource: file
name: product-docs
config:
  content: "@./docs/product-manual.pdf"
  content_type: "application/pdf"
---
# Knowledge base references the file's URL
provider: agno
resource: knowledge
name: product-knowledge
config:
  source_url:
    provider: pragma
    resource: file
    name: product-docs
    field: outputs.public_url
When the file is updated (re-uploaded with new content), the knowledge base automatically receives the new URL and can re-ingest the document.

​
Supported Content Types

Any MIME type is supported. Common examples:
Content TypeUse Case
application/pdfDocuments, manuals
application/jsonConfiguration files, datasets
application/jsonlTraining data, log files
text/plainText documents, CSV files
text/csvTabular data
image/png, image/jpegImages

​
Next Steps

Reactive Pipelines

Build pipelines where file changes automatically propagate.

CLI Resources

Full resource management commands.