Skip to main content

​
List Artifacts (Machine Auth)

Lists all artifacts within a dock using machine authentication. Returns artifact metadata, hashes, and download URLs. 
GET /v1/machine/docks/:dockId/artifacts

​
Authentication

Required: Bearer token from OAuth2 token endpoint 
Authorization: Bearer dyt_live_...
Required Scope: artifacts:read

​
Path Parameters

ParameterTypeRequiredDescription
dockIdstringRequiredTarget dock ID (must match machine client’s dock scope)

​
Query Parameters

ParameterTypeDefaultDescription
limitinteger20Maximum items to return (max 1000)
offsetinteger0Number of items to skip
searchstring-Filter by filename (partial match)
metadataobject-Filter by metadata fields (JSON string)
createdAfterstring-Filter by creation date (ISO 8601)
createdBeforestring-Filter by creation date (ISO 8601)

​
Example Request

# List all artifacts
curl https://api.docyard.io/v1/machine/docks/dock_metro_general/artifacts \
  -H "Authorization: Bearer dyt_live_qrstuvwx..."

# Search by filename
curl "https://api.docyard.io/v1/machine/docks/dock_metro_general/artifacts?search=discharge" \
  -H "Authorization: Bearer dyt_live_qrstuvwx..."

# Filter by metadata
curl "https://api.docyard.io/v1/machine/docks/dock_metro_general/artifacts?metadata={\"patientId\":\"12345\"}" \
  -H "Authorization: Bearer dyt_live_qrstuvwx..."

# Paginate results
curl "https://api.docyard.io/v1/machine/docks/dock_metro_general/artifacts?limit=50&offset=100" \
  -H "Authorization: Bearer dyt_live_qrstuvwx..."

# Date range filter
curl "https://api.docyard.io/v1/machine/docks/dock_metro_general/artifacts?createdAfter=2024-03-01T00:00:00Z" \
  -H "Authorization: Bearer dyt_live_qrstuvwx..."

​
Response

{
  "data": [
    {
      "id": "art_01HQ3K9B2...",
      "dockId": "dock_metro_general",
      "filename": "discharge-summary-12345.pdf",
      "contentType": "application/pdf",
      "size": 245760,
      "hash": "sha256:abc123def456...",
      "metadata": {
        "patientId": "12345",
        "mrn": "MRN-2024-001",
        "documentType": "discharge-summary"
      },
      "createdAt": "2024-03-01T12:30:00.000Z",
      "updatedAt": "2024-03-01T12:30:00.000Z",
      "downloadUrl": "https://s3.amazonaws.com/...",
      "expiresAt": "2024-03-01T13:30:00.000Z"
    },
    {
      "id": "art_01HQ3L9C3...",
      "dockId": "dock_metro_general",
      "filename": "lab-results-67890.pdf",
      "contentType": "application/pdf",
      "size": 156780,
      "hash": "sha256:def789ghi012...",
      "metadata": {
        "patientId": "67890",
        "testType": "blood-panel"
      },
      "createdAt": "2024-03-01T11:15:00.000Z",
      "updatedAt": "2024-03-01T11:15:00.000Z",
      "downloadUrl": "https://s3.amazonaws.com/...",
      "expiresAt": "2024-03-01T12:15:00.000Z"
    }
  ],
  "meta": {
    "total": 247,
    "page": 1,
    "pageSize": 20,
    "hasMore": true
  }
}

​
Response Fields

FieldTypeDescription
dataarrayList of artifacts
data[].idstringArtifact identifier (prefix: art_)
data[].filenamestringOriginal filename
data[].contentTypestringMIME type
data[].sizeintegerFile size in bytes
data[].hashstringSHA-256 hash for integrity verification
data[].metadataobjectCustom JSON attributes
data[].createdAtstringISO 8601 creation timestamp
data[].updatedAtstringISO 8601 last update timestamp
data[].downloadUrlstringPresigned download URL (1 hour expiry)
data[].expiresAtstringDownload URL expiration timestamp
meta.totalintegerTotal artifacts matching query
meta.hasMorebooleanWhether more results exist

​
Download URLs

Each artifact includes a presigned download URL valid for 1 hour: 
# Download directly from S3
curl -o discharge-summary.pdf "https://s3.amazonaws.com/..."
Automatic Rotation: If a URL expires, re-list artifacts to get fresh download URLs.

​
Metadata Filtering

Filter artifacts by metadata fields: 
# Single field
curl "https://api.docyard.io/v1/machine/docks/{dockId}/artifacts?metadata={\"patientId\":\"12345\"}"

# Multiple fields
curl "https://api.docyard.io/v1/machine/docks/{dockId}/artifacts?metadata={\"patientId\":\"12345\",\"documentType\":\"discharge-summary\"}"

​
Error Handling

StatusCondition
401Missing, invalid, or expired token
403Insufficient scope (need artifacts:read)
403Dock access denied
404Dock not found

​
Use Cases

Batch Retrieval: List all artifacts from the last 24 hours for automated processing: 
curl "https://api.docyard.io/v1/machine/docks/{dockId}/artifacts?createdAfter=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ)"
Patient-Specific: Find all documents for a specific patient: 
curl "https://api.docyard.io/v1/machine/docks/{dockId}/artifacts?metadata={\"patientId\":\"12345\"}"
Incremental Sync: Paginate through all artifacts for data synchronization: 
offset = 0
while True:
    response = list_artifacts(offset=offset, limit=100)
    process_artifacts(response['data'])
    
    if not response['meta']['hasMore']:
        break
    offset += 100

​
Code Example

Python - Batch Download: 
import requests

def download_all_artifacts(dock_id, token):
    headers = {'Authorization': f'Bearer {token}'}
    offset = 0
    
    while True:
        response = requests.get(
            f'https://api.docyard.io/v1/machine/docks/{dock_id}/artifacts',
            headers=headers,
            params={'limit': 100, 'offset': offset}
        )
        response.raise_for_status()
        data = response.json()
        
        for artifact in data['data']:
            # Download each artifact
            download_response = requests.get(artifact['downloadUrl'])
            with open(artifact['filename'], 'wb') as f:
                f.write(download_response.content)
            print(f"Downloaded: {artifact['filename']}")
        
        if not data['meta']['hasMore']:
            break
        offset += 100

# Usage
download_all_artifacts('dock_metro_general', 'dyt_live_...')

​
Rate Limits

Machine authentication endpoints have separate rate limits from user API keys:
ResourceLimit
List requests100/minute per machine client
Download URLs1000/hour per machine client
Exceeding limits returns 429 Too Many Requests with Retry-After header.