cURL

curl -sS -X PUT "http://localhost:3001/api/v1/artifacts/$artifact_id/content" \
  -H "Authorization: Bearer $FACTROVE_API_KEY" \
  -F "file=@./fixtures/hello.html"

import { readFile } from "node:fs/promises";

const artifactId = process.env.ARTIFACT_ID;
const API_ORIGIN = "http://localhost:3001";

const bytes = await readFile("./fixtures/hello.html");
const htmlBlob = new Blob([bytes], { type: "text/html" });
const form = new FormData();
form.append("file", htmlBlob, "hello.html");

const response = await fetch(`${API_ORIGIN}/api/v1/artifacts/${artifactId}/content`, {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.FACTROVE_API_KEY}` },
  body: form,
});

import os
import requests

with open("./fixtures/hello.html", "rb") as handle:
    response = requests.put(
        f"http://localhost:3001/api/v1/artifacts/{os.environ['ARTIFACT_ID']}/content",
        headers={"Authorization": f"Bearer {os.environ['FACTROVE_API_KEY']}"},
        files={"file": ("hello.html", handle, "text/html")},
    )

{
  "artifact": {
    "id": "11111111-1111-4111-8111-111111111111",
    "creatorUserId": "user_example",
    "organizationId": null,
    "accessType": "private",
    "filename": "11111111-1111-4111-8111-111111111111.html",
    "name": "hello",
    "mimeType": "text/html",
    "sizeBytes": 527,
    "createdAt": "2026-10-21T12:00:00.000Z",
    "updatedAt": "2026-10-21T12:00:00.000Z",
    "uploadedAt": "2026-10-21T12:00:00.000Z",
    "viewerUrl": "http://localhost:3000/artifacts/11111111-1111-4111-8111-111111111111",
    "contentUrl": "http://localhost:3001/api/v1/artifacts/11111111-1111-4111-8111-111111111111/content",
    "shared": false,
    "passwordProtected": false
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "accessType cannot be changed when replacing content."
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Sign in to continue."
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This request origin is not allowed."
  }
}

{
  "error": {
    "code": "ARTIFACT_NOT_FOUND",
    "message": "Artifact was not found."
  }
}

{
  "error": {
    "code": "CONTENT_CONFLICT",
    "message": "Another replace finished first. Upload again to replace the current content."
  }
}

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "The file exceeds the 10 MiB limit."
  }
}

{
  "error": {
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "Only .html and .htm files are supported."
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  }
}

{
  "error": {
    "code": "STORAGE_UNAVAILABLE",
    "message": "Object storage is unavailable."
  }
}

Artifacts

Replace an artifact's stored HTML

Owner only. Multipart field file is the same HTML validation as create: one non-empty .html or .htm file, at most 10 MiB, UTF-8. Optional name is set in the same conditional update as the new object and the revision check. Omit name and that update does not change the column, so the current name stays. An invalid name is 400 INVALID_REQUEST and leaves the current HTML in place. accessType is rejected. The id, current access, and any share token stay the same. The new object is written first, then the row points at it. Another replace of the same revision is 409 CONTENT_CONFLICT and does not change the name. An acknowledged or successfully reconciled update returns 200 even if a later replace has landed since. The 200 shows the artifact’s current state, which may already include a later replace. A content commit that throws can still land later, and that landing sets the name when this request included one. If the client sees 500 it should GET the artifact before retrying. Cookie-authenticated writes need an allowed Origin.

PUT

api

artifacts

{id}

content

cURL

curl -sS -X PUT "http://localhost:3001/api/v1/artifacts/$artifact_id/content" \
  -H "Authorization: Bearer $FACTROVE_API_KEY" \
  -F "file=@./fixtures/hello.html"

import { readFile } from "node:fs/promises";

const artifactId = process.env.ARTIFACT_ID;
const API_ORIGIN = "http://localhost:3001";

const bytes = await readFile("./fixtures/hello.html");
const htmlBlob = new Blob([bytes], { type: "text/html" });
const form = new FormData();
form.append("file", htmlBlob, "hello.html");

const response = await fetch(`${API_ORIGIN}/api/v1/artifacts/${artifactId}/content`, {
  method: "PUT",
  headers: { Authorization: `Bearer ${process.env.FACTROVE_API_KEY}` },
  body: form,
});

import os
import requests

with open("./fixtures/hello.html", "rb") as handle:
    response = requests.put(
        f"http://localhost:3001/api/v1/artifacts/{os.environ['ARTIFACT_ID']}/content",
        headers={"Authorization": f"Bearer {os.environ['FACTROVE_API_KEY']}"},
        files={"file": ("hello.html", handle, "text/html")},
    )

{
  "artifact": {
    "id": "11111111-1111-4111-8111-111111111111",
    "creatorUserId": "user_example",
    "organizationId": null,
    "accessType": "private",
    "filename": "11111111-1111-4111-8111-111111111111.html",
    "name": "hello",
    "mimeType": "text/html",
    "sizeBytes": 527,
    "createdAt": "2026-10-21T12:00:00.000Z",
    "updatedAt": "2026-10-21T12:00:00.000Z",
    "uploadedAt": "2026-10-21T12:00:00.000Z",
    "viewerUrl": "http://localhost:3000/artifacts/11111111-1111-4111-8111-111111111111",
    "contentUrl": "http://localhost:3001/api/v1/artifacts/11111111-1111-4111-8111-111111111111/content",
    "shared": false,
    "passwordProtected": false
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "accessType cannot be changed when replacing content."
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Sign in to continue."
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This request origin is not allowed."
  }
}

{
  "error": {
    "code": "ARTIFACT_NOT_FOUND",
    "message": "Artifact was not found."
  }
}

{
  "error": {
    "code": "CONTENT_CONFLICT",
    "message": "Another replace finished first. Upload again to replace the current content."
  }
}

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "The file exceeds the 10 MiB limit."
  }
}

{
  "error": {
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "Only .html and .htm files are supported."
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  }
}

{
  "error": {
    "code": "STORAGE_UNAVAILABLE",
    "message": "Object storage is unavailable."
  }
}

Authorizations

Authorization

string

header

required

Factrove API key, usually prefixed ftrv_. Send Authorization: Bearer <key>. Product routes do not accept x-api-key as a credential. A present Authorization header that is not a valid key does not fall back to the session cookie.

Path Parameters

string<uuid>

required

Artifact UUID.

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

multipart/form-data

One HTML file and an optional library name. Do not send accessType.

file

required

One non-empty .html or .htm file, at most 10 MiB. accessType is not accepted.

name

string

Library name. Normalized to NFC, then trimmed. One line of 1 to 120 Unicode code points. U+0000–U+001F, U+007F–U+009F, U+2028, and U+2029 are rejected before trimming, so a trailing break is not removed. An invalid value is 400 INVALID_REQUEST with message name must be one line of 1 to 120 characters.

Required string length: 1 - 120

Response

The same artifact id with the new size and upload time. The 200 shows the artifact's current state, which may already include a later replace.

artifact

object

required

Show child attributes

Overview

Health

Auth

Artifacts

Shares

Public

Replace an artifact's stored HTML

Authorizations

Path Parameters

Body

Response