Skip to main content

​
Artifact Ingestion

This guide covers strategies for uploading artifacts to the lake.

​
Basic Upload

​
Single Artifact Upload

curl -X POST https://api.docyard.io/v1/ramp/artifacts \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl-ins-dec-001",
    "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-abc123",
  "status": "active",
  "created_at": "2026-03-15T10:30:00Z"
}

​
Response Fields

FieldDescription
idUnique artifact identifier
statusCurrent status (uploaded, active, revoked)
created_atTimestamp of upload

​
Content Formats

​
Base64 Encoded

Send file as base64 string: 
{
  "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQo=",
  "content_type": "application/pdf"
}

​
Multipart Form Data

For large files, use multipart upload: 
curl -X POST https://api.docyard.io/v1/ramp/artifacts \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -F "[email protected]" \
  -F "template_id=tmpl-ins-dec-001" \
  -F "locks={\"policy_number\":{\"value\":\"POL-12345678\"}}"

​
Batch Upload

For bulk uploads, use batch endpoint: 
curl -X POST https://api.docyard.io/v1/ramp/artifacts/batch \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{
    "artifacts": [
      {
        "template_id": "tmpl-ins-dec-001",
        "locks": {
          "policy_number": { "value": "POL-11111111" },
          "effective_date": { "value": "2026-03-15" }
        },
        "threshold": 20,
        "content": "<base64-pdf-1>"
      },
      {
        "template_id": "tmpl-ins-dec-001",
        "locks": {
          "policy_number": { "value": "POL-22222222" },
          "effective_date": { "value": "2026-03-15" }
        },
        "threshold": 20,
        "content": "<base64-pdf-2>"
      }
    ]
  }'
Response: 
{
  "batch_id": "batch-xyz789",
  "status": "processing",
  "total": 2,
  "processed": 0
}

​
Check Batch Status

curl -X GET https://api.docyard.io/v1/ramp/artifacts/batch/batch-xyz789 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
Response: 
{
  "batch_id": "batch-xyz789",
  "status": "completed",
  "total": 2,
  "processed": 2,
  "succeeded": 2,
  "failed": 0,
  "artifacts": [
    { "id": "art-001", "status": "active" },
    { "id": "art-002", "status": "active" }
  ]
}

​
Override Weights

By default, weights come from the template. Override per artifact: 
{
  "template_id": "tmpl-ins-dec-001",
  "locks": {
    "policy_number": { "value": "POL-12345678", "weight": 30 },
    "effective_date": { "value": "2026-03-15", "weight": 15 }
  },
  "threshold": 30
}
Result: Only the policy number (30) meets the threshold.

​
Lock Value Validation

Values are validated against template rules: 
{
  "template_id": "tmpl-ins-dec-001",
  "locks": {
    "policy_number": { "value": "INVALID" }
  }
}
Error Response: 
{
  "error": "validation_error",
  "message": "Lock value validation failed",
  "details": {
    "field": "locks.policy_number",
    "issue": "pattern_mismatch",
    "expected": "^POL-[0-9]{8}$"
  }
}

​
Deduplication

Prevent duplicate uploads with idempotency keys: 
curl -X POST https://api.docyard.io/v1/ramp/artifacts \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-Idempotency-Key: unique-upload-idempotency-key-12345" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
If the same idempotency key is used twice, the second request returns the original result.

​
Nightly Batch Upload Strategy

For insurance carriers with nightly batches:

​
1. Prepare Manifest

{
  "manifest_id": "manifest-2026-03-15",
  "template_id": "tmpl-ins-dec-001",
  "artifacts": [
    {
      "idempotency_key": "POL-11111111-2026-03-15",
      "locks": {
        "policy_number": { "value": "POL-11111111" },
        "effective_date": { "value": "2026-03-15" }
      },
      "content_hash": "sha256:abc123..."
    }
  ]
}

​
2. Upload with Hash Validation

curl -X POST https://api.docyard.io/v1/ramp/artifacts/batch \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "Content-Type: application/json" \
  -d '{
    "manifest_id": "manifest-2026-03-15",
    "artifacts": [ ... ]
  }'

​
3. Verify Upload Results

Check which artifacts were created vs. skipped: 
{
  "batch_id": "batch-xyz789",
  "results": [
    {
      "idempotency_key": "POL-11111111-2026-03-15",
      "status": "created",
      "artifact_id": "art-001"
    },
    {
      "idempotency_key": "POL-22222222-2026-03-15",
      "status": "skipped",
      "reason": "duplicate"
    }
  ]
}

​
Managing Artifacts

​
List Artifacts

curl -X GET "https://api.docyard.io/v1/ramp/artifacts?status=active&limit=50&page=1" \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"

​
Get Artifact Details

curl -X GET https://api.docyard.io/v1/ramp/artifacts/art-abc123 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
Response: 
{
  "id": "art-abc123",
  "template_id": "tmpl-ins-dec-001",
  "template_name": "Insurance Declaration Page",
  "status": "active",
  "locks": {
    "policy_number": { "value": "POL-12345678", "weight": 20 },
    "effective_date": { "value": "2026-03-15", "weight": 10 }
  },
  "threshold": 20,
  "created_at": "2026-03-15T10:30:00Z",
  "retrieval_count": 5
}

​
Revoke Artifact

Remove access to a specific artifact: 
curl -X DELETE https://api.docyard.io/v1/ramp/artifacts/art-abc123 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
Response: 
{
  "id": "art-abc123",
  "status": "revoked",
  "message": "Artifact has been revoked. Collectors can no longer retrieve."
}

​
Rate Limits

Upload TypeLimit
Single upload100/minute
Batch upload10 batches/minute
Max batch size100 artifacts

​
Best Practices

​
1. Use Batch Uploads for Large Volumes

Instead of 100 single uploads, use one batch.

​
2. Implement Retry Logic

async function uploadWithRetry(artifact, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.ramp.upload(artifact);
    } catch (error) {
      if (error.status >= 500) {
        await sleep(1000 * Math.pow(2, i));
        continue;
      }
      throw error;
    }
  }
}

​
3. Use Idempotency Keys

Prevent duplicate uploads in case of retries.

​
4. Validate Before Upload

Validate lock values client-side before uploading: 
const template = await client.templates.get('tmpl-ins-dec-001');

for (const lock of template.locks) {
  if (lock.required && !artifact.locks[lock.name]) {
    throw new Error(`Missing required lock: ${lock.name}`);
  }
}

​
Next Steps