Skip to main content

​
Artifacts

An artifact is any document, file, or digital content stored in the lake. When a distributor uploads through a ramp, the result is an artifact that collectors can retrieve through a dock.

​
What Makes an Artifact

Every artifact consists of:
ComponentDescriptionExample
ContentThe actual file dataPDF, image, document
Artifact TypeTemplate used for upload”Insurance Declaration”
Document TypeCategory (system lock)“declaration_page”
LocksMetadata fields with values{ policy_number: "POL-123" }
WeightsScores for each lock{ policy_number: 20 }
ThresholdMinimum score for access20
OwnerDistributor who uploadedDistributor ID
IDUnique artifact identifierart-abc123
Created AtUpload timestamp2026-03-15T10:30:00Z

​
Artifact Lifecycle

   Uploaded ──► Active ──► Revoked
      │           │           │
      │           │           │
      ▼           ▼           ▼
   Initial      Live &    No longer
   state       retrievable  accessible

​
Status Definitions

StatusDescriptionRetrievable?
uploadedJust uploaded, being processed❌ No
activeReady for retrieval✅ Yes
revokedManually revoked by distributor❌ No

​
Artifact Metadata

​
System Locks (Required)

Every artifact must have these:
LockData TypeDescription
document_typestringCategory of document

​
Custom Locks (From Template)

Defined by the artifact type template:
LockData TypeExample Value
policy_numberstring”POL-12345678”
effective_datedate”2026-03-15”
mortgagee_namestring”FirstCity Bank”

​
Weights

Each lock has an associated weight: 
{
  "locks": {
    "policy_number": { "value": "POL-12345678", "weight": 20 },
    "effective_date": { "value": "2026-03-15", "weight": 10 },
    "mortgagee_name": { "value": "FirstCity Bank", "weight": 5 }
  },
  "threshold": 20
}

​
Uploading Artifacts

​
Process Flow

  1. Select Template: Choose an artifact type template
  2. Provide Values: Fill in lock values for the artifact
  3. Set Access: Optionally adjust weights and threshold
  4. Upload Content: Send the file data
  5. Receive Confirmation: Get artifact ID

​
Example Upload

POST /api/v1/ramp/artifacts
{
  "template_id": "uuid-of-insurance-declaration-template",
  "locks": {
    "policy_number": { "value": "POL-12345678" },
    "effective_date": { "value": "2026-03-15" },
    "mortgagee_name": { "value": "FirstCity Bank" }
  },
  "threshold": 20,
  "content": "<base64-encoded-pdf>"
}

​
Response

{
  "id": "art-abc123xyz",
  "status": "active",
  "artifact_type": "Insurance Declaration",
  "document_type": "declaration_page",
  "locks": {
    "policy_number": { "value": "POL-12345678", "weight": 20 },
    "effective_date": { "value": "2026-03-15", "weight": 10 },
    "mortgagee_name": { "value": "FirstCity Bank", "weight": 5 }
  },
  "threshold": 20,
  "created_at": "2026-03-15T10:30:00Z"
}

​
Retrieving Artifacts

​
Process Flow

  1. Search: Find artifacts matching criteria
  2. Select: Choose the artifact to retrieve
  3. Present Keys: Provide keys you have access to
  4. Get Result: Receive file if score ≥ threshold

​
Example Retrieval

POST /api/v1/dock/retrieve/art-abc123xyz
{
  "keys": {
    "policy_number": "POL-12345678"
  }
}

​
Successful Response

{
  "id": "art-abc123xyz",
  "status": "granted",
  "score": 20,
  "threshold": 20,
  "content": "<file-data>",
  "content_type": "application/pdf",
  "artifact_type": "Insurance Declaration",
  "document_type": "declaration_page",
  "metadata": {
    "policy_number": "POL-12345678",
    "effective_date": "2026-03-15",
    "mortgagee_name": "FirstCity Bank"
  }
}

​
Denied Response

{
  "id": "art-abc123xyz",
  "status": "denied",
  "score": 5,
  "threshold": 20,
  "message": "Score (5) is below threshold (20). Provide additional keys."
}

​
Batch Operations

​
Batch Upload

Upload multiple artifacts at once: 
POST /api/v1/ramp/artifacts/batch
{
  "artifacts": [
    {
      "template_id": "uuid",
      "locks": { "policy_number": { "value": "POL-111" } },
      "threshold": 20,
      "content": "<file-1>"
    },
    {
      "template_id": "uuid",
      "locks": { "policy_number": { "value": "POL-222" } },
      "threshold": 20,
      "content": "<file-2>"
    }
  ]
}

​
Batch Retrieval

Retrieve multiple artifacts in one request: 
POST /api/v1/dock/retrieve/batch
{
  "artifact_ids": ["art-abc123", "art-def456", "art-ghi789"],
  "keys": {
    "policy_number": "POL-111"
  }
}
Collectors can search the lake: 
POST /api/v1/dock/search
{
  "filters": {
    "document_type": "declaration_page",
    "policy_number": "POL-123",
    "effective_date_after": "2026-01-01"
  },
  "pagination": {
    "page": 1,
    "limit": 50
  }
}

​
Search Response

{
  "results": [
    {
      "id": "art-abc123",
      "artifact_type": "Insurance Declaration",
      "document_type": "declaration_page",
      "locks": {
        "policy_number": "POL-12345678",
        "effective_date": "2026-03-15"
      },
      "accessible": true,
      "score_if_keys_provided": 20
    },
    {
      "id": "art-def456",
      "artifact_type": "Insurance Declaration",
      "document_type": "declaration_page",
      "locks": {
        "policy_number": "POL-87654321",
        "effective_date": "2026-02-20"
      },
      "accessible": false,
      "score_if_keys_provided": 0
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150
  }
}

​
Revoking Artifacts

Distributors can revoke artifacts: 
DELETE /api/v1/ramp/artifacts/art-abc123xyz
After revocation, collectors cannot retrieve the artifact.

​
Next Steps