> ## 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.

# Artifacts

> Documents stored in the lake

# Artifacts

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

## What Makes an Artifact

Every artifact consists of:

| Component         | Description                 | Example                        |
| ----------------- | --------------------------- | ------------------------------ |
| **Content**       | The actual file data        | PDF, image, document           |
| **Artifact Type** | Template used for upload    | "Insurance Declaration"        |
| **Document Type** | Category (system lock)      | "declaration\_page"            |
| **Locks**         | Metadata fields with values | `{ policy_number: "POL-123" }` |
| **Weights**       | Scores for each lock        | `{ policy_number: 20 }`        |
| **Threshold**     | Minimum score for access    | 20                             |
| **Owner**         | Distributor who uploaded    | Distributor ID                 |
| **ID**            | Unique artifact identifier  | `art-abc123`                   |
| **Created At**    | Upload timestamp            | 2026-03-15T10:30:00Z           |

## Artifact Lifecycle

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

### Status Definitions

| Status     | Description                     | Retrievable? |
| ---------- | ------------------------------- | ------------ |
| `uploaded` | Just uploaded, being processed  | ❌ No         |
| `active`   | Ready for retrieval             | ✅ Yes        |
| `revoked`  | Manually revoked by distributor | ❌ No         |

## Artifact Metadata

### System Locks (Required)

Every artifact must have these:

| Lock            | Data Type | Description          |
| --------------- | --------- | -------------------- |
| `document_type` | string    | Category of document |

### Custom Locks (From Template)

Defined by the artifact type template:

| Lock             | Data Type | Example Value    |
| ---------------- | --------- | ---------------- |
| `policy_number`  | string    | "POL-12345678"   |
| `effective_date` | date      | "2026-03-15"     |
| `mortgagee_name` | string    | "FirstCity Bank" |

### Weights

Each lock has an associated weight:

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

```json theme={null}
POST /api/v1/upload/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

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

```json theme={null}
POST /api/v1/dock/retrieve/art-abc123xyz
{
  "keys": {
    "policy_number": "POL-12345678"
  }
}
```

### Successful Response

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

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

```json theme={null}
POST /api/v1/upload/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:

```json theme={null}
POST /api/v1/dock/retrieve/batch
{
  "artifact_ids": ["art-abc123", "art-def456", "art-ghi789"],
  "keys": {
    "policy_number": "POL-111"
  }
}
```

## Artifact Search

Collectors can search the lake:

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

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

```json theme={null}
DELETE /api/v1/upload/artifacts/art-abc123xyz
```

After revocation, collectors cannot retrieve the artifact.

***

## Next Steps

* Learn about \[Uploads & Docks]\(/concepts/upload endpoints-and-docks)
* Understand [Lock-Key-Weight](/concepts/lock-key-weight)
* See the [API Reference](/api-reference/artifacts)