Create Artifact (Machine Auth)

Creates a new artifact using machine authentication. This endpoint is designed for automated systems to upload documents via OAuth2 client credentials.

POST /v1/machine/docks/:dockId/artifacts

Authentication

Required: Bearer token from OAuth2 token endpoint

Authorization: Bearer dyt_live_...

Required Scope: artifacts:write

Path Parameters

Parameter	Type	Required	Description
`dockId`	string	Required	Target dock ID (must match machine client’s dock scope)

Request Body

Parameter	Type	Required	Description
`filename`	string	Required	Original filename with extension
`contentType`	string	Optional	MIME type (auto-detected if not provided)
`size`	integer	Optional	File size in bytes (for validation)
`metadata`	object	Optional	Custom JSON metadata
`hash`	string	Optional	Pre-computed SHA-256 hash for deduplication

Example Request

Healthcare (EHR)
Financial Services
Real Estate

curl -X POST https://api.docyard.io/v1/machine/docks/dock_metro_general/artifacts \
  -H "Authorization: Bearer dyt_live_qrstuvwx..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "discharge-summary-12345.pdf",
    "contentType": "application/pdf",
    "size": 245760,
    "metadata": {
      "patientId": "12345",
      "mrn": "MRN-2024-001",
      "encounterId": "ENC-56789",
      "documentType": "discharge-summary",
      "department": "cardiology",
      "attendingPhysician": "Dr. Sarah Johnson"
    }
  }'

curl -X POST https://api.docyard.io/v1/machine/docks/dock_mortgage_ops/artifacts \
  -H "Authorization: Bearer dyt_live_qrstuvwx..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "closing-disclosure-2024-001.pdf",
    "metadata": {
      "loanId": "LOAN-2024-001",
      "borrowerName": "John & Jane Homeowner",
      "propertyAddress": "123 Main St, Anytown, ST 12345",
      "loanOfficer": "Alice Smith",
      "closingDate": "2024-03-15",
      "documentType": "closing-disclosure"
    }
  }'

curl -X POST https://api.docyard.io/v1/machine/docks/dock_title_policies/artifacts \
  -H "Authorization: Bearer dyt_live_qrstuvwx..." \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "title-policy-ABC-12345.pdf",
    "metadata": {
      "orderId": "ORD-ABC-12345",
      "propertyAddress": "456 Oak Ave, Somewhere, ST 67890",
      "buyer": "Smith Family Trust",
      "seller": "Johnson Estate",
      "premium": 1250.00,
      "underwriter": "First American Title"
    }
  }'

Response

{
  "id": "art_01HQ3K9B2...",
  "dockId": "dock_metro_general",
  "filename": "discharge-summary-12345.pdf",
  "contentType": "application/pdf",
  "size": 245760,
  "hash": "sha256:abc123def456...",
  "storageKey": "docks/dock_metro_general/artifacts/...",
  "metadata": {
    "patientId": "12345",
    "mrn": "MRN-2024-001",
    "documentType": "discharge-summary"
  },
  "isDuplicate": false,
  "createdAt": "2024-03-01T12:30:00.000Z",
  "updatedAt": "2024-03-01T12:30:00.000Z",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "uploadId": "upload_01HQ3L..."
}

Response Fields

Field	Type	Description
`id`	string	Unique artifact identifier (prefix: `art_`)
`dockId`	string	Owning dock
`filename`	string	Original filename
`contentType`	string	MIME type
`size`	integer	File size in bytes
`hash`	string	SHA-256 hash for integrity verification
`storageKey`	string	Internal storage location
`metadata`	object	Custom JSON attributes
`isDuplicate`	boolean	Whether this was a duplicate upload
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp
`uploadUrl`	string	Presigned URL for direct S3 upload
`uploadId`	string	Upload job ID for tracking

Deduplication

If you upload content with the same SHA-256 hash, the existing artifact is returned with isDuplicate: true:

{
  "id": "art_01HQ3K9B2...",
  "filename": "discharge-summary-12345.pdf",
  "hash": "sha256:abc123def456...",
  "isDuplicate": true,
  "createdAt": "2024-02-15T10:00:00.000Z"
}

No additional storage is consumed for duplicates.

Upload Process

The response includes a presigned S3 URL for direct file upload:

# Step 1: Create artifact record
curl -X POST https://api.docyard.io/v1/machine/docks/{dockId}/artifacts \
  ...
# Response includes uploadUrl

# Step 2: Upload file directly to S3
curl -X PUT "https://s3.amazonaws.com/..." \
  -H "Content-Type: application/pdf" \
  --data-binary @discharge-summary.pdf

# Step 3: Complete upload
curl -X POST https://api.docyard.io/v1/machine/docks/{dockId}/artifacts/upload/complete \
  -H "Authorization: Bearer dyt_live_..." \
  -d '{"uploadId": "upload_01HQ3L...", "s3Key": "..."}'

See the Machine Authentication Guide for complete upload workflows.

Error Handling

Status	Condition
`400`	Invalid request body or missing required fields
`401`	Missing, invalid, or expired token
`403`	Insufficient scope (need `artifacts:write`)
`403`	Dock access denied (client scoped to different dock)
`404`	Dock not found
`409`	File size exceeds limit

Insufficient Scope:

{
  "statusCode": 403,
  "message": "Insufficient scope. Required: artifacts:write",
  "error": "Forbidden"
}

Dock Mismatch (client scoped to different dock):

{
  "statusCode": 403,
  "message": "Access denied to dock dock_other",
  "error": "Forbidden"
}

Best Practices

Metadata: Include identifiers that help recipients route and process documents:

Healthcare: Patient ID, MRN, encounter ID, document type
Financial: Loan ID, borrower name, closing date
Real Estate: Order ID, property address, parties involved

Deduplication: Pre-compute SHA-256 hashes if you want to check for duplicates before upload:

# Compute hash locally
hash=$(sha256sum document.pdf | awk '{print $1}')

# Include in request
curl -X POST ... -d "{..., \"hash\": \"$hash\"}"

List Artifacts (Machine) — List artifacts via machine auth
Issue Token — Get access token
Standard Artifacts API — User-driven artifact creation

API Reference

Organizations

Parties

Machine Authentication

Docks

Artifacts

Recipients

Recipient Groups

Policies

Retrieval

Secrets

Audit

Notifications

Identity

Create Artifact (Machine Auth)