Skip to main content

​
Retrieve Artifact

Retrieve a single artifact by presenting your keys.

​
Endpoint

POST /dock/retrieve/{artifact_id}

​
Path Parameters

ParameterTypeRequiredDescription
artifact_idstringYesThe artifact ID to retrieve

​
Request

​
Headers

HeaderRequiredDescription
X-API-KeyYesYour API key
X-API-SecretYesYour API secret
Content-TypeYesMust be application/json

​
Body Parameters

ParameterTypeRequiredDescription
keysobjectYesKeys you are presenting

​
Example Request

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)

{
  "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)

{
  "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)

{
  "error": "not_found",
  "message": "Artifact not found",
  "details": {
    "artifact_id": "art-nonexistent"
  },
  "request_id": "req-abc123xyz"
}

​
Unauthorized Lock Type (403)

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

​
Response Fields (Granted)

FieldTypeDescription
idstringArtifact identifier
statusstringAlways granted
scoreintegerCalculated score from keys
thresholdintegerRequired threshold
contentstringBase64-encoded file
content_typestringMIME type
content_sizeintegerFile size in bytes
artifact_typestringArtifact type name
document_typestringDocument category
metadataobjectAll lock values
retrieved_atstringRetrieval timestamp

​
Response Fields (Denied)

FieldTypeDescription
idstringArtifact identifier
statusstringAlways denied
scoreintegerCalculated score from keys
thresholdintegerRequired threshold
keys_providedarrayKeys you presented
keys_neededarrayAdditional keys needed
messagestringExplanation of denial

​
Code Examples

​
Node.js

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

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'])}")