Artifacts Client

The artifacts client manages the full lifecycle of knowledge artifacts - from creation to publishing to analytics.

Methods

`list()`

List all artifacts you own.

artifacts = await client.artifacts.list()
for artifact in artifacts:
    print(f"{artifact.title}  -  {artifact.status} ({artifact.domain})")

Returns: list[Artifact]

`get(artifact_id)`

Get a single artifact by ID.

artifact = await client.artifacts.get(artifact_id="your-artifact-id")
print(f"{artifact.title}: quality={artifact.quality_score}")

Parameters:

Name	Type	Description
`artifact_id`	`str`	The artifact's UUID

Returns: Artifact

`create_from_agent(agent_id)`

Extract knowledge from an agent's conversation traces and create an artifact.

artifact = await client.artifacts.create_from_agent(
    agent_id="your-agent-id"
)
print(f"Created: {artifact.title} ({artifact.id})")

Kate analyzes the agent's traces - diagnostic patterns, decision flows, tool usage patterns - and packages the most valuable knowledge into a structured artifact.

Parameters:

Name	Type	Description
`agent_id`	`str`	The agent whose traces to extract from

Returns: Artifact (in draft status)

`upload(name, file_path, agent_id, domain)`

Upload a document as an artifact.

from pathlib import Path

artifact = await client.artifacts.upload(
    name="E-commerce Pricing Framework",
    file_path="./pricing-playbook.pdf",
    agent_id=None,        # optional: associate with an agent
    domain="e-commerce",
)

Supported formats: PDF, Markdown, plain text. Maximum size: 20 MB.

Parameters:

Name	Type	Default	Description
`name`	`str`	required	Artifact title
`file_path`	`str \| Path`	required	Path to the file
`agent_id`	`str \| None`	`None`	Optional agent to associate with
`domain`	`str`	`"general"`	Domain classification

Returns: Artifact (in draft status)

`analyze_coverage(artifact_id)`

Analyze the topic coverage of an artifact. Useful before publishing to understand what the artifact covers well and where it's thin.

artifact = await client.artifacts.analyze_coverage(
    artifact_id="your-artifact-id"
)
# Coverage results are stored on the artifact

Parameters:

Name	Type	Description
`artifact_id`	`str`	The artifact to analyze

Returns: Artifact (with updated coverage data)

`publish(artifact_id)`

Publish an artifact, making it discoverable by buyer agents. Automatically generates the cover if it hasn't been created yet.

artifact = await client.artifacts.publish(
    artifact_id="your-artifact-id"
)
print(f"Status: {artifact.status}")  # "pending_review"

Parameters:

Name	Type	Description
`artifact_id`	`str`	The artifact to publish

Returns: Artifact (status transitions to pending_review)

`analytics(artifact_id)`

Get performance analytics for an artifact.

analytics = await client.artifacts.analytics(
    artifact_id="your-artifact-id"
)
print(f"Subscribers: {analytics.subscriber_count}")
print(f"Total queries: {analytics.total_queries}")
print(f"Tokens earned: {analytics.tokens_earned}")

Parameters:

Name	Type	Description
`artifact_id`	`str`	The artifact to get analytics for

Returns: ArtifactAnalytics

Data Models

`Artifact`

@dataclass
class Artifact:
    id: str
    title: str
    domain: str
    status: str              # draft, pending_review, listed, suspended
    description: str
    hosting_type: str | None # kate_hosted
    creation_type: str | None # kh_agent, kh_upload
    visibility: str | None   # private, team, listed, paid
    price_tokens: int        # Subscription cost
    per_query_tokens: int    # Per-query cost
    version: str             # Semantic version
    quality_score: float | None
    covers_generated: bool
    user_id: str | None
    agent_id: str | None
    created_at: str | None
    updated_at: str | None

`ArtifactAnalytics`

@dataclass
class ArtifactAnalytics:
    subscriber_count: int
    total_queries: int
    tokens_earned: int

Next Steps

Seller Quickstart - end-to-end artifact creation
Discovery Client - buyer-side discovery
Briefs Client - knowledge briefs

Artifacts Client

On this page