Upload or replace assembly and XML artifacts with the Link REST API. For authentication, environment addresses, and shared response conventions, see API conventions.
Required permission: API Artifact Upload (API_Artifact_Upload), included in the API Artifacts role. Artifacts are shared within the environment; replacing one can affect every configuration that references it.
Assembly artifacts
POST /api/rest/operation/artifact/upload-assembly?fileName=<filename>
Send one compiled .NET DLL as the raw body. Use a build compatible with the target Link installation; see Artifact development.
Link inspects the DLL to identify the artifact factory and type. A DLL yielding multiple detected Link artifacts is rejected. A loadable DLL with no detected artifact is stored as a dependency assembly. Upload any required managed dependencies individually before the DLL that uses them. This operation does not install ZIP archives or NuGet packages.
Link matches an existing assembly artifact by its stored filename:
|
Value |
New artifact |
Matching filename |
|---|---|---|
|
Artifact ID |
Generated |
Preserved |
|
DLL bytes |
Stored |
Replaced |
|
Display name and description |
Read from factory, falling back to assembly identity |
Preserved |
|
Assembly identity, factory class, artifact type |
Read from DLL |
Updated from DLL |
Keep fileName stable when releasing a new assembly version. Changing the filename can create another artifact; existing configuration references will still point to the old artifact. The display name and assembly identity are not the upload match key. There is no overwrite switch.
Example
Upload the compiled file ./release/Contoso.Link.OrderStep.dll. Replace the environment and PAT placeholders; the command uses Bash syntax.
LINK_API_BASE='https://<your-link-api-host>'
LINK_PAT='<your-personal-access-token>'
curl --silent --show-error --fail-with-body --include \
--user ":${LINK_PAT}" \
--header 'Content-Type: application/octet-stream' \
--data-binary '@./release/Contoso.Link.OrderStep.dll' \
"${LINK_API_BASE}/api/rest/operation/artifact/upload-assembly?fileName=Contoso.Link.OrderStep.dll"
Success is 200 OK with an empty body, with no returned artifact ID. Upload each dependency using the same operation and that dependency's own filename.
XML artifacts
POST /api/rest/operation/artifact/upload-xml
Send the XML file as the raw body and these query parameters:
|
Parameter |
Meaning |
|---|---|
|
|
Stored filename and XML update match key |
|
|
Display name for a new artifact |
|
|
Description for a new artifact, or for an existing artifact whose description is null |
|
|
|
Supply all four parameters on every upload, including updates. artifactName, description, and xmlType must be nonblank.
A matching XML filename preserves the artifact ID, existing name, non-null description, stored filename, and XML type. Only the bytes are replaced. Supplying another valid xmlType does not change an existing artifact's type. Without a match, Link creates an artifact from the supplied metadata. Assembly and XML filename lookups are separate.
Example
Upload the prepared stylesheet ./release/order-to-erp.xslt as Orders to ERP.xslt. Query values are percent-encoded; the body contains the original file bytes.
LINK_API_BASE='https://<your-link-api-host>'
LINK_PAT='<your-personal-access-token>'
curl --silent --show-error --fail-with-body --include \
--user ":${LINK_PAT}" \
--header 'Content-Type: application/xml' \
--data-binary '@./release/order-to-erp.xslt' \
"${LINK_API_BASE}/api/rest/operation/artifact/upload-xml?fileName=Orders%20to%20ERP.xslt&artifactName=Orders%20to%20ERP&description=Maps%20orders%20to%20ERP&xmlType=Xslt"
Success is 200 OK with an empty body. For an XSD, use the same operation with xmlType=Schema, the schema bytes, and appropriate metadata.
Both operations accept raw bytes, not multipart form data or a JSON/base64 wrapper. The content types in the examples are suitable values; these actions do not enforce those particular media types.
After upload
New artifacts still need to be selected in the relevant Link configuration, such as an itinerary step or a stylesheet reference. Upload saves the artifact and its metadata and can register declared error codes. It does not create the flow configuration that uses the artifact. Updates retain existing identifier-based references without migrating their configuration.
Link invalidates artifact caches and propagates changes between hosts. Already active assembly executions can continue with the previous version; a 200 response does not confirm that every host has switched. Upload does not restart hosts. Verify the new artifact in its configured flow; if an old version remains active, investigate cache propagation and that consumer's lifecycle.
Upload failures
-
Missing filename, or blank XML name, description, or type: 400.
-
Nonblank unsupported
xmlType: 500 in this implementation. -
Invalid DLL, missing dependencies, multiple detected artifacts, malformed XSLT XML, or invalid error-code declarations can produce 500.
-
XSLT is parsed during error-code discovery, but not fully compiled or tested. Schema upload does not compile the schema. Validate the file before uploading and test its intended use afterwards.
After an error or uncertain response, check the stored artifact before uploading again. Assembly bytes are saved before error-code registration, so registration can fail after the DLL was saved. XSLT error-code registration occurs before file persistence, so those registrations can succeed even if the later file save fails.
Serialize uploads for the same filename. Repeating an upload can update audit metadata, register error codes, and invalidate caches again. Separate file uploads are not one atomic deployment.