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

# Uploads & Docks

> How artifacts enter and exit the lake

# Uploads & Docks

The lake has two types of access points:

* **Uploads**: Where artifacts enter the lake (for distributors)
* **Docks**: Where artifacts leave the lake (for collectors)

## Uploads

A upload endpoint is an authenticated connection that allows distributors to upload artifacts into the lake.

### What Distributors Do at Uploads

1. **Authenticate** using API credentials
2. **Select Artifact Type** template
3. **Provide Lock Values** (metadata for the document)
4. **Set Weights & Threshold** for access control
5. **Upload Content** (the actual file)

### Upload Example

A distributor uploads an insurance declaration:

```json theme={null}
POST /api/v1/upload/artifacts
{
  "template_id": "uuid-of-insurance-declaration-template",
  "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,
  "content": "<base64-encoded-file>"
}
```

### Key Upload Concepts

| Concept            | Description                                |
| ------------------ | ------------------------------------------ |
| **Upload ID**      | Unique identifier for each upload endpoint |
| **Distributor ID** | Who owns this upload endpoint              |
| **API Keys**       | Authentication credentials                 |
| **Rate Limits**    | Upload throttling                          |

***

## Docks

A dock is an authenticated connection that allows collectors to retrieve artifacts from the lake.

### What Collectors Do at Docks

1. **Authenticate** using API credentials
2. **Search** for artifacts by lock type values
3. **Present Keys** for lock types they have access to
4. **Retrieve** artifacts if score ≥ threshold

### Dock Example

A collector searches for insurance declarations:

```json theme={null}
POST /api/v1/dock/search
{
  "locks": {
    "policy_number": "POL-12345678"
  }
}
```

If the collector has the matching key (policy number), they get access.

### Key Dock Concepts

| Concept              | Description                     |
| -------------------- | ------------------------------- |
| **Dock ID**          | Unique identifier for each dock |
| **Collector ID**     | Who owns this dock              |
| **API Keys**         | Authentication credentials      |
| **Lock Permissions** | Which lock types they can use   |

***

## Distributor vs. Collector Flow

<details>
  <summary>👆 Click to expand: Upload vs Retrieval Flow</summary>

  ```mermaid theme={null}
  flowchart LR
      subgraph UPLOAD["DISTRIBUTOR FLOW"]
          R1[Select Template]
          R2[Provide Locks & Weights]
          R3[Upload Content]
          R1 --> R2 --> R3 --> R4[Store in Lake]
      end

      subgraph LAKE["THE LAKE"]
          A1[Artifact 1]
          A2[Artifact 2]
          A3[Artifact 3]
      end

      subgraph DOCK["COLLECTOR FLOW"]
          D1[Search Lake]
          D2[Present Keys]
          D3[Check Score]
          D4{Score >= Threshold?}
          D5[Access Granted]
          D6[Access Denied]
          D1 --> D2 --> D3 --> D4
          D4 -->|Yes| D5
          D4 -->|No| D6
      end

      R4 --> A1
      R4 --> A2
      R4 --> A3

      A1 --> D1
      A2 --> D1
      A3 --> D1

      style UPLOAD fill:#e8f5e9,stroke:#2e7d32
      style LAKE fill:#e1f5fe,stroke:#01579b
      style DOCK fill:#fff3e0,stroke:#ef6c00
      style D5 fill:#c8e6c9,stroke:#2e7d32
      style D6 fill:#ffcdd2,stroke:#c62828
  ```
</details>

## Key Differences

| Aspect             | Upload                            | Dock                  |
| ------------------ | --------------------------------- | --------------------- |
| **Purpose**        | Upload artifacts                  | Retrieve artifacts    |
| **Action**         | Push into lake                    | Fish from lake        |
| **Required Info**  | Template, locks, weights, content | Search criteria, keys |
| **Result**         | Artifact stored in lake           | Artifact returned     |
| **Authentication** | Distributor credentials           | Collector credentials |

## Authentication

Both upload endpoints and docks use API key authentication:

```bash theme={null}
# Upload (Distributor)
curl -X POST https://api.docyard.io/v1/upload/artifacts \
  -H "X-API-Key: distributor_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Dock (Collector)
curl -X POST https://api.docyard.io/v1/dock/search \
  -H "X-API-Key: collector_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

## Rate Limits

| Endpoint Type   | Default Limit       | Notes                |
| --------------- | ------------------- | -------------------- |
| Upload (Upload) | 100 requests/minute | For artifact uploads |
| Dock (Search)   | 300 requests/minute | For searches         |
| Dock (Retrieve) | 100 requests/minute | For retrievals       |

***

## Next Steps

* Learn about [Artifact Types](/concepts/artifact-types)
* Understand the [Lock-Key-Weight Model](/concepts/lock-key-weight)
* See [Distributors](/concepts/distributors) for upload workflow
* See [Collectors](/concepts/collectors) for retrieval workflow