Artifact Queries

Once your agent subscribes to an artifact, it can query the artifact - a Q&A interface that returns answers grounded in the seller's knowledge without exposing the underlying content.

How Querying Works

Your agent sends a question with context
Kate routes the query to the appropriate artifact
The artifact retrieves relevant knowledge and generates a grounded answer
The answer is returned with a confidence score and related topics
Per-query tokens are charged to your wallet and credited to the seller

Querying via SDK

response = await client.query.ask(
    artifact_id="artifact-id",
    agent_id="your-agent-id",
    question="What's the best keyword clustering strategy for B2B SaaS content?",
)
print(f"Answer: {response.answer}")
print(f"Confidence: {response.confidence}")
print(f"Related: {response.related_topics}")
print(f"Tokens charged: {response.tokens_charged}")

Querying via API

curl -X POST "https://api.projectkate.com/artifacts/{artifact_id}/query" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What keyword clustering strategy works for B2B SaaS?",
    "buyer_agent_id": "your-agent-id"
  }'

Response:

{
  "answer": "For B2B SaaS content, topic clustering outperforms...",
  "confidence": 0.87,
  "related_topics": ["content gap analysis", "search intent mapping"],
  "tokens_charged": 15
}

Query Response Fields

Field	Type	Description
`answer`	`string`	The grounded answer from the artifact
`confidence`	`float`	How confident the answer is (0.0 to 1.0)
`related_topics`	`list[string]`	Related topics the artifact can answer
`tokens_charged`	`integer`	Tokens deducted for this query

Requirements

Your agent must have an active subscription to the artifact
Your wallet must have sufficient tokens for the per-query charge
The question should be within the artifact's domain for best results

Tips for Better Queries

Be specific - "What's the optimal H-1B visa filing strategy for a software engineer from India?" is better than "Tell me about visas"
Include context - pass relevant user context (location, industry, situation) for more targeted answers
Match the domain - query artifacts within their stated domain for highest confidence

Next Steps

Pricing & Tokens - understanding query costs
Query API - API reference