How to organize Artifacts

Imagine the Artifacts system as a Digital Catalog or the “inventory” that your AI Agent can consult to show products to customers.

To organize your products, the logic works from the most “General” to the most “Specific”.

​

1. The Structure (The Hierarchy)

1. Main Category (Parent): This is the larger group. (Ex: Shorts)
2. Subcategory (Child): This is a division within the larger group. (Ex: Women’s Shorts)
3. Artifact (The Product): This is the actual item you sell. (Ex: Shorts Model Y)
4. Media (Photos/Videos): These are the images or videos of that item. (Ex: Blue Photo, Red Photo)

​

2. Practical Step-by-Step via API

See how to structure your data using the API endpoints:

​

Step 1: Create the Main Category

First, create the general “drawer” (container).

• Endpoint: POST /artifact-categories
• Body: { "name": "Shorts" }
• Result: The system creates the category and returns the id (e.g., cat_shorts_123).

​

Step 2: Create the Subcategory

Now, organize inside the “Shorts” container using the ID returned in the previous step.

• Endpoint: POST /artifact-categories
• Body: { "name": "Women's Shorts", "parentId": "cat_shorts_123" }
• Result: The system understands that “Women’s Shorts” is a child of “Shorts”. Save this new id (e.g., cat_fem_456).

​

Step 3: Create the Artifact (The Product)

Register the product itself, linking it to the subcategory.

• Endpoint: POST /artifacts
• Body:

  {
    "name": "Shorts Model Y",
    "price": 99.00,
    "description": "Comfortable shorts, light fabric, ideal for summer.",
    "categoryId": "cat_fem_456"
  }
  

• Result: The product was created on the right shelf. Save the artifact id (e.g., art_short_789).

​

Step 4: Add Media (Photos/Videos)

Finally, upload the images for the created product.

• Endpoint: POST /artifacts/media/upload
• Form-Data:
  • file: (The image/video file)
  • artifact_id: art_short_789
  • name: “Blue Photo”
• Result: When the customer asks about “Shorts Model Y”, the AI will be able to send these media files.

​

3. Visual Summary

📁 Category: Shorts
    │
    └── 📂 Subcategory: Women's Shorts
          │
          └── 🏷️ Artifact: Shorts Model Y ($ 99.00)
                │
                ├── 🖼️ Media: Blue Photo
                ├── 🖼️ Media: Red Photo
                └── 🎥 Media: Product Video