Skip to main content

​
Upload Artifact

Upload a single artifact to the lake through your ramp.

​
Endpoint

POST /ramp/artifacts

​
Request

​
Headers

HeaderRequiredDescription
X-API-KeyYesYour API key
X-API-SecretYesYour API secret
Content-TypeYesMust be application/json
X-Idempotency-KeyNoUnique key to prevent duplicate uploads

​
Body Parameters

ParameterTypeRequiredDescription
template_idstringYesID of the artifact type template
locksobjectYesLock values and weights
thresholdintegerYesMinimum score for access (1-100)
contentstringYesBase64-encoded file content
content_typestringNoMIME type (default: application/pdf)

​
Locks Object

Each lock in the object should have:
ParameterTypeRequiredDescription
valuestring/numberYesThe lock value
weightintegerNoOverride template weight

​
Example Request

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 "X-Idempotency-Key: POL-12345678-2026-03-15" \
  -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": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQo=",
    "content_type": "application/pdf"
  }'

​
Response

​
Success (201 Created)

{
  "id": "art-abc123xyz",
  "status": "active",
  "template_id": "tmpl-ins-dec-001",
  "template_name": "Insurance 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"
}

​
Response Fields

FieldTypeDescription
idstringUnique artifact identifier
statusstringCurrent status: active, processing, revoked
template_idstringTemplate used
template_namestringTemplate name
locksobjectLock values and weights
thresholdintegerAccess threshold
created_atstringUpload timestamp

​
Error Responses

​
Validation Error (422)

{
  "error": "validation_error",
  "message": "Lock value validation failed",
  "details": {
    "field": "locks.policy_number",
    "issue": "pattern_mismatch",
    "expected": "^POL-[0-9]{8}$",
    "received": "POL-INVALID"
  },
  "request_id": "req-abc123xyz"
}

​
Template Not Found (404)

{
  "error": "template_not_found",
  "message": "Template not found or not published",
  "details": {
    "template_id": "tmpl-nonexistent"
  },
  "request_id": "req-abc123xyz"
}

​
Missing Required Lock (422)

{
  "error": "validation_error",
  "message": "Missing required lock",
  "details": {
    "field": "locks.effective_date",
    "required": true
  },
  "request_id": "req-abc123xyz"
}

​
Idempotency

Use the X-Idempotency-Key header to prevent duplicate uploads: 
curl -X POST https://api.docyard.io/v1/ramp/artifacts \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-Idempotency-Key: unique-key-12345" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
If you submit the same request with the same idempotency key, you’ll receive the original response without creating a duplicate.

​
Code Examples

​
Node.js

const fs = require('fs');

const pdfBuffer = fs.readFileSync('declaration.pdf');
const base64Content = pdfBuffer.toString('base64');

const artifact = await client.ramp.upload({
  templateId: 'tmpl-ins-dec-001',
  locks: {
    policy_number: { value: 'POL-12345678' },
    effective_date: { value: '2026-03-15' },
    mortgagee_name: { value: 'FirstCity Bank' }
  },
  threshold: 20,
  content: base64Content,
  contentType: 'application/pdf'
});

​
Python

import base64

with open('declaration.pdf', 'rb') as f:
    content = base64.b64encode(f.read()).decode()

artifact = client.ramp.upload(
    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=content,
    content_type='application/pdf'
)