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

# Retrieve Artifact

> Retrieve an artifact using your keys

# Retrieve Artifact

Retrieve a single artifact by presenting your keys.

## Endpoint

```
POST /dock/retrieve/{artifact_id}
```

## Path Parameters

| Parameter     | Type   | Required | Description                 |
| ------------- | ------ | -------- | --------------------------- |
| `artifact_id` | string | Yes      | The artifact ID to retrieve |

## Request

### Headers

| Header         | Required | Description                |
| -------------- | -------- | -------------------------- |
| `X-API-Key`    | Yes      | Your API key               |
| `X-API-Secret` | Yes      | Your API secret            |
| `Content-Type` | Yes      | Must be `application/json` |

### Body Parameters

| Parameter | Type   | Required | Description             |
| --------- | ------ | -------- | ----------------------- |
| `keys`    | object | Yes      | Keys you are presenting |

## Example Request

```bash theme={null}
curl -X POST https://api.docyard.io/v1/dock/retrieve/art-abc123 \
  -H "X-API-Key: dk_live_coll_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_coll_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": {
      "policy_number": "POL-12345678"
    }
  }'
```

## Response

### Access Granted (200 OK)

```json theme={null}
{
  "id": "art-abc123",
  "status": "granted",
  "score": 20,
  "threshold": 20,
  "content": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PAovRmlsdGVy...",
  "content_type": "application/pdf",
  "content_size": 245678,
  "artifact_type": "Insurance Declaration Page",
  "document_type": "declaration_page",
  "metadata": {
    "policy_number": "POL-12345678",
    "effective_date": "2026-03-15",
    "mortgagee_name": "FirstCity Bank"
  },
  "retrieved_at": "2026-03-15T14:30:00Z"
}
```

### Access Denied (200 OK)

```json theme={null}
{
  "id": "art-abc123",
  "status": "denied",
  "score": 5,
  "threshold": 20,
  "keys_provided": ["mortgagee_name"],
  "keys_needed": ["policy_number"],
  "message": "Score (5) is below threshold (20). Provide additional keys."
}
```

### Artifact Not Found (404)

```json theme={null}
{
  "error": "not_found",
  "message": "Artifact not found",
  "details": {
    "artifact_id": "art-nonexistent"
  },
  "request_id": "req-abc123xyz"
}
```

### Unauthorized Lock Type (403)

```json theme={null}
{
  "error": "unauthorized_lock_type",
  "message": "You are not authorized to use the 'tax_id' lock type",
  "request_id": "req-abc123xyz"
}
```

## Response Fields (Granted)

| Field           | Type    | Description                |
| --------------- | ------- | -------------------------- |
| `id`            | string  | Artifact identifier        |
| `status`        | string  | Always `granted`           |
| `score`         | integer | Calculated score from keys |
| `threshold`     | integer | Required threshold         |
| `content`       | string  | Base64-encoded file        |
| `content_type`  | string  | MIME type                  |
| `content_size`  | integer | File size in bytes         |
| `artifact_type` | string  | Artifact type name         |
| `document_type` | string  | Document category          |
| `metadata`      | object  | All lock values            |
| `retrieved_at`  | string  | Retrieval timestamp        |

## Response Fields (Denied)

| Field           | Type    | Description                |
| --------------- | ------- | -------------------------- |
| `id`            | string  | Artifact identifier        |
| `status`        | string  | Always `denied`            |
| `score`         | integer | Calculated score from keys |
| `threshold`     | integer | Required threshold         |
| `keys_provided` | array   | Keys you presented         |
| `keys_needed`   | array   | Additional keys needed     |
| `message`       | string  | Explanation of denial      |

## Code Examples

### Node.js

```javascript theme={null}
const result = await client.dock.retrieve('art-abc123', {
  keys: {
    policy_number: 'POL-12345678'
  }
});

if (result.status === 'granted') {
  // Save file
  const buffer = Buffer.from(result.content, 'base64');
  fs.writeFileSync('declaration.pdf', buffer);
  
  console.log(`Downloaded ${result.content_size} bytes`);
} else {
  console.log(`Access denied: ${result.message}`);
  console.log(`Keys provided: ${result.keys_provided.join(', ')}`);
  console.log(`Keys needed: ${result.keys_needed.join(', ')}`);
}
```

### Python

```python theme={null}
result = client.dock.retrieve('art-abc123', {
    'keys': {
        'policy_number': 'POL-12345678'
    }
})

if result['status'] == 'granted':
    # Save file
    import base64
    content = base64.b64decode(result['content'])
    with open('declaration.pdf', 'wb') as f:
        f.write(content)
    
    print(f"Downloaded {result['content_size']} bytes")
else:
    print(f"Access denied: {result['message']}")
    print(f"Keys provided: {', '.join(result['keys_provided'])}")
    print(f"Keys needed: {', '.join(result['keys_needed'])}")
```

***

## Related Endpoints

* [Search Artifacts](/api-reference/docks/search) - Find artifacts
* [Batch Retrieve](/api-reference/docks/batch-retrieve) - Retrieve multiple artifacts
* [Async Retrieve](/api-reference/docks/async-retrieve) - Start async retrieval job