> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docyard.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifact Ingestion

> Upload documents to the lake

# Artifact Ingestion

This guide covers strategies for uploading artifacts to the lake.

## Basic Upload

### Single Artifact Upload

```bash theme={null}
curl -X POST https://api.docyard.io/v1/upload/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:**

```json theme={null}
{
  "id": "art-abc123",
  "status": "active",
  "created_at": "2026-03-15T10:30:00Z"
}
```

### Response Fields

| Field        | Description                                |
| ------------ | ------------------------------------------ |
| `id`         | Unique artifact identifier                 |
| `status`     | Current status (uploaded, active, revoked) |
| `created_at` | Timestamp of upload                        |

## Content Formats

### Base64 Encoded

Send file as base64 string:

```json theme={null}
{
  "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQo=",
  "content_type": "application/pdf"
}
```

### Multipart Form Data

For large files, use multipart upload:

```bash theme={null}
curl -X POST https://api.docyard.io/v1/upload/artifacts \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -F "file=@declaration.pdf" \
  -F "template_id=tmpl-ins-dec-001" \
  -F "locks={\"policy_number\":{\"value\":\"POL-12345678\"}}"
```

## Batch Upload

For bulk uploads, use batch endpoint:

```bash theme={null}
curl -X POST https://api.docyard.io/v1/upload/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:**

```json theme={null}
{
  "batch_id": "batch-xyz789",
  "status": "processing",
  "total": 2,
  "processed": 0
}
```

### Check Batch Status

```bash theme={null}
curl -X GET https://api.docyard.io/v1/upload/artifacts/batch/batch-xyz789 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
```

**Response:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "template_id": "tmpl-ins-dec-001",
  "locks": {
    "policy_number": { "value": "INVALID" }
  }
}
```

**Error Response:**

```json theme={null}
{
  "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:

```bash theme={null}
curl -X POST https://api.docyard.io/v1/upload/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

```json theme={null}
{
  "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

```bash theme={null}
curl -X POST https://api.docyard.io/v1/upload/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:

```json theme={null}
{
  "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

```bash theme={null}
curl -X GET "https://api.docyard.io/v1/upload/artifacts?status=active&limit=50&page=1" \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
```

### Get Artifact Details

```bash theme={null}
curl -X GET https://api.docyard.io/v1/upload/artifacts/art-abc123 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
```

**Response:**

```json theme={null}
{
  "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:

```bash theme={null}
curl -X DELETE https://api.docyard.io/v1/upload/artifacts/art-abc123 \
  -H "X-API-Key: dk_live_dist_aaaaaaaa"
```

**Response:**

```json theme={null}
{
  "id": "art-abc123",
  "status": "revoked",
  "message": "Artifact has been revoked. Collectors can no longer retrieve."
}
```

## Rate Limits

| Upload Type    | Limit             |
| -------------- | ----------------- |
| Single upload  | 100/minute        |
| Batch upload   | 10 batches/minute |
| Max batch size | 100 artifacts     |

## Best Practices

### 1. Use Batch Uploads for Large Volumes

Instead of 100 single uploads, use one batch.

### 2. Implement Retry Logic

```javascript theme={null}
async function uploadWithRetry(artifact, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.upload endpoint.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:

```javascript theme={null}
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

* **[Creating Artifact Types](/guides/creating-artifact-types)** - Design templates
* **\[First Upload Setup]\(/guides/first-upload endpoint)** - Configure your upload endpoint
* **[API Reference](/api-reference/artifacts)** - Full artifact API