Skip to content

Artifacts ​

Artifacts are client deliverables — agreements, offer docs, concepts, project updates, demos, and files you track and send to a contact. They are not public News updates and not agent knowledge Documents.

Install the Artifacts native app from team Apps to manage deliverables in the dashboard (/artifacts). Agents can also use warps, MCP tools, and the HTTP API.

Overview ​

  • Register a deliverable with title, type, optional URL / access password (hashed at rest), attached media, and extra link
  • Attach a contact (and optionally an order / quote)
  • Status flow: draft → ready → sent (or archived)
  • Deliver from the dashboard with a message you write — pick the sending agent (same idea as campaigns; that agent’s email/SMS/WhatsApp integration is used) — or Generate with AI to run the artifact-deliver warp in chat (draft → edit → approve → send). Structured document blocks are still appended on send when present.

Types ​

TypeTypical use
agreementKurzvereinbarung / contract link
offerAngebot / offer document
conceptConcept or pitch
updateClient-facing project update (not a public News update)
demoInteractive demo URL
fileFile or download link
otherAnything else

Statuses ​

StatusMeaning
draftNot ready to send
readyReady to deliver
sentMessage sent; deliveredAt set
archivedSoft-retired
  1. Create each deliverable (deck, demo, agreement, …) with contact and URLs and/or media, status ready
  2. Deliver with one or more artifact IDs — one message covering all links (include any password you just set; JoAi does not return stored passwords) → edit → approve → send
  3. All included artifacts become sent; a delivery record stores what went out

For a local PDF/image via MCP: media_upload → create_artifact with media: ["…"] (and optional url) → deliver_artifacts. url and media are both optional.

Ownership vs delivery ​

  • Artifact contactId — who the deliverable belongs to (optional until send; used as the default recipient).
  • Delivery contactId — who that specific message was sent to (always set on the delivery record).

One delivery can cover several artifacts. Delivery history keeps the recipient even if an artifact’s contact is later changed.

Every ready or sent artifact has a public page at https://joai.ai/{locale}/artifacts?id={id}. The artifact's own url stays the deliverable link (for example the PDF or demo).

If the artifact has a password, the page shows a password form before revealing the content. The shared API is GET /v1/artifacts/shared/{id}; send the password in the X-Artifact-Password header (the ?password= query is also accepted). Until the correct password is supplied it returns 403 with requiresPassword: true. Draft and archived artifacts are not public.

Delivery messages include this link automatically, even when the artifact has no structured blocks. The artifact card in chat also previews image URLs and links to the public page once the artifact exists.

In the app ​

  1. Install Artifacts under team Apps
  2. Open Artifacts in the sidebar, or open a Contact → Deliveries tab to see that client’s deliverables
  3. Create / edit deliverables (from the contact tab, the contact is prefilled), then Deliver (manual) or Generate with AI (opens artifact-deliver in chat)

For agents (warps) ​

WarpPurpose
artifact-createCreate a deliverable
artifact-listList / filter artifacts (optional ids)
artifact-getLoad one artifact
artifact-updateEdit fields or status
artifact-deletePermanently remove a record
artifact-deliverDraft → single approve (editable message) → send. Auto mode runs through; manual mode waits for approve

MCP tools ​

ToolPurpose
create_artifactCreate a deliverable (url and/or media IDs optional)
list_artifactsList / filter
get_artifactLoad one
update_artifactEdit (including media)
delete_artifactDelete
deliver_artifactsDispatch artifact-deliver: draft message, then one approve step (editable). Auto mode sends; manual mode waits for approve

create_artifact / update_artifact: pass media as team media IDs from media_upload (e.g. ["abc123"]). url remains optional for external links.

deliver_artifacts is the only delivery path — same draft → approve / auto-mode model as campaigns. File links come from the drafted message (media[].url in the artifact JSON), not a second server-side append.

See SKILL.md and Warps.

API ​

  • GET|POST /v1/artifacts
  • GET /v1/artifacts/shared/{id} — shared page data; optional X-Artifact-Password header, returns 403 with requiresPassword: true while protected
  • GET|PATCH|DELETE /v1/artifacts/{id}
  • POST /v1/artifacts/deliver — body: artifactIds[], message, integration (email | sms | whatsapp), optional subject, contactIds[], agentId (agent UUID; defaults to request agent or the team’s first agent)
  • GET /v1/artifacts?ids=id1,id2 — load a specific set

See also Contacts for messaging channels and News for public updates (different product).