SDK artifacts

The ArtifactManager — reached through ivy.artifacts — lets you download the file-based outputs a completed job produces, such as PDB structures, SDF molecules, CSV reports, and JSON results. Reach for it after a job finishes, when the inline result isn't enough and you need the actual output file as a blob, text string, or parsed JSON. It works from the presigned S3 URLs the Jobs reference surfaces on a completed job, and pairs with the Client you construct first.

SDK Artifacts Reference

The ArtifactManager handles downloading file-based job outputs from time-limited presigned S3 URLs. Supports binary, text, and JSON formats.

Access via ivy.artifacts.

Overview

Completed jobs may produce downloadable artifacts stored in AWS S3:

• PDB files — Protein structures from ESMFold, DiffDock
• SDF files — Molecular structures from docking, fragment growing
• CSV reports — Tabular analysis results
• JSON files — Structured prediction outputs

Artifacts are accessed via time-limited presigned URLs that typically expire after 1 hour.

artifacts.getDownloadUrl(jobId)

Get the presigned download URL for a completed job's artifacts.

async getDownloadUrl(jobId: string): Promise<string | null>

Parameters:

Returns: The presigned S3 URL, or null if the job has no downloadable artifacts (results are inline JSON only).

Throws: IvyApiError with isNotFound if the job doesn't exist.

Examples

const url = await ivy.artifacts.getDownloadUrl("job_abc123")
if (url) {
  window.open(url) // Direct browser download
}

Note: If the URL has expired (403 on download), call this method again for a fresh URL.

artifacts.download(presignedUrl)

Download artifact content as a Blob. Best for binary files or creating client-side download links.

async download(presignedUrl: string): Promise<Blob>

Throws: IvyApiError if the download fails (e.g., URL expired — status 403).

Examples

// Create a download link in the browser
const blob = await ivy.artifacts.download(presignedUrl)
const url = URL.createObjectURL(blob)
const a = document.createElement("a")
a.href = url
a.download = "structure.pdb"
a.click()
URL.revokeObjectURL(url)

artifacts.downloadText(presignedUrl)

Download artifact as a UTF-8 text string. Suitable for PDB, SDF, CSV, FASTA formats.

async downloadText(presignedUrl: string): Promise<string>

Throws: IvyApiError if the download fails.

Examples

const pdb = await ivy.artifacts.downloadText(presignedUrl)
const lines = pdb.split("\n")
const atoms = lines.filter(l => l.startsWith("ATOM"))
console.log(`${atoms.length} atoms in structure`)

Parsing JSON artifacts

The SDK has no JSON helper. Download the file as text and parse it:

interface DockingResult {
  poses: Array<{ score: number; rmsd: number; pdb: string }>
  metadata: { protein_name: string; ligand_smiles: string }
}

const results = JSON.parse(await ivy.artifacts.downloadText(url)) as DockingResult
console.log(`Best pose score: ${results.poses[0].score}`)

Workflow Example

// 1. Submit job and wait for completion
const result = await ivy.jobs.submitAndWait({
  toolName: "esmfold",
  parameters: { protein_sequence: "MKFLILLFNILCLFPVLAADNH" },
})

// 2. Get the download URL
if (result.presignedUrl) {
  // 3a. Download as text (PDB file)
  const pdb = await ivy.artifacts.downloadText(result.presignedUrl)
  console.log(pdb.substring(0, 100))
} else {
  // 3b. Results are inline JSON
  console.log(result.result)
}

S3 Key Format

Artifacts are stored with the following S3 key structure:

{user_id}/jobs/{job_id}/{artifact_type}/{filename}

Example:

user_abc123/jobs/job_def456/structures/predicted_structure.pdb

You don't need to know the key — the presigned URL handles access.