API reference · Assets
POST/api/v1/assets/{id}/documents

Associate document with asset

Creates a document_associations row that links the path asset ID to the supplied document_id. The body is validated with createAssetDocumentSchema; document_id is required and notes is optional. The service inserts entity_type=asset, entity_id from the path, document_id, notes, tenant from context, and created_at, then returns the inserted row. It does not verify that the asset or document belongs to the same tenant before insert, does not set created_by, and publishes no event. Foreign-key or unique constraint errors surface through handleApiError. In the current route wiring, req.context may be absent because no route-level API-key auth wrapper sets it, causing a 500 before insert.

RBAC · asset

Path parameters

idstring <uuid>Required
Asset UUID from assets.asset_id.

Request body

Content type: application/json · schema AssetDocumentAssociationRequest

document_idstring <uuid>Required
Document UUID from documents.document_id to associate with the asset.
notesstring
Optional notes stored on document_associations.notes.

Response body

Success response 201 · schema AssetDocumentAssociationResponse

successbooleanRequired
Enum: true
dataobjectRequired
dataobjectRequired
association_idstring <uuid>Required
Primary key from document_associations.association_id.
entity_typestringRequired
Entity type stored on document_associations; always asset for these routes.
Enum: asset
entity_idstring <uuid>Required
Asset UUID from document_associations.entity_id.
document_idstring <uuid>Required
Document UUID from document_associations.document_id.
notesstringNullable
Optional association notes.
tenantstring <uuid>Required
Tenant UUID from document_associations.tenant.
created_atstring <date-time>
Association creation timestamp.
original_filenamestring
Original filename from the joined documents table, present on list responses.
file_sizenumber
File size in bytes from the joined documents table, present on list responses.
mime_typestring
MIME type from the joined documents table, present on list responses.
uploaded_atstring <date-time>
Document upload timestamp from the joined documents table, present on list responses.
metaobjectRequired
timestampstring <date-time>Required
versionstringRequired

Response codes

201
Document association created successfully.
400
Request body validation failed or a database foreign-key reference is invalid.
401
x-api-key is missing at middleware.
403
Authenticated request context lacks permission to update asset documents when auth wiring is present.
409
Duplicate association rejected by a database unique constraint.
500
Unexpected error, including missing req.context in the current route wiring.