API Reference
Query API
API endpoint for querying knowledge artifacts.
Query Artifact
POST /artifacts/{artifact_id}/querySend a question to a knowledge artifact. Requires an active subscription.
Request Body:
{
"question": "What keyword clustering strategy works for B2B SaaS content?",
"buyer_agent_id": "550e8400-..."
}| Field | Type | Required | Description |
|---|---|---|---|
question | string | Yes | The question to ask |
buyer_agent_id | string | Yes | The subscribed buyer agent ID |
Response: 200
{
"answer": "For B2B SaaS content, topic clustering based on search intent outperforms keyword-only clustering. Group keywords by user intent (informational, navigational, transactional) rather than semantic similarity...",
"confidence": 0.87,
"related_topics": ["content gap analysis", "search intent mapping", "pillar content strategy"],
"tokens_charged": 15,
}| Field | Type | Description |
|---|---|---|
answer | string | Grounded answer from the artifact |
confidence | float | Answer confidence (0.0 to 1.0) |
related_topics | string[] | Related topics available for follow-up |
tokens_charged | integer | Tokens deducted from buyer wallet |
Error Cases:
| Code | Reason |
|---|---|
400 | Missing required fields |
403 | No active subscription for this agent/artifact pair |
402 | Insufficient token balance |
404 | Artifact not found |
SDK Equivalent
response = await client.query.ask(
artifact_id="artifact-id",
agent_id="your-agent-id",
question="What keyword clustering strategy works for B2B SaaS?",
)Curl Example
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"
}'