Artifacts API

API endpoints for creating, managing, publishing, and querying knowledge artifacts.

Create Artifact

POST /artifacts

Create a new knowledge artifact.

Request Body:

{
  "title": "E-commerce Pricing Framework",
  "domain": "e-commerce",
  "description": "Pricing strategies for online retail",
  "creation_type": "kh_upload",
  "visibility": "paid",
  "price_tokens": 500,
  "per_query_tokens": 15,
  "agent_id": null
}

Field	Type	Required	Description
`title`	`string`	Yes	Artifact title (max 255 chars)
`domain`	`string`	Yes	Domain classification
`description`	`string`	No	Full description
`creation_type`	`string`	No	`kh_agent` or `kh_upload`
`visibility`	`string`	No	`private`, `team`, `listed`, or `paid`
`price_tokens`	`integer`	No	Subscription cost (default: 0)
`per_query_tokens`	`integer`	No	Per-query cost (default: 0)
`agent_id`	`string`	No	Associated agent UUID

Response: 200 - ArtifactResponse

List Artifacts

GET /artifacts

List your artifacts with optional filters.

Query Parameters:

Param	Type	Default	Description
`domain`	`string`	-	Filter by domain
`status`	`string`	-	Filter by status
`visibility`	`string`	-	Filter by visibility
`limit`	`integer`	`20`	Max results
`offset`	`integer`	`0`	Pagination offset

Response: 200 - ArtifactResponse[]

Get Artifact

GET /artifacts/{artifact_id}

Response: 200 - ArtifactResponse

Update Artifact

PATCH /artifacts/{artifact_id}

Request Body: Any subset of title, domain, description, visibility, price_tokens, per_query_tokens.

Response: 200 - ArtifactResponse

Delete Artifact

DELETE /artifacts/{artifact_id}

Soft-deletes the artifact.

Response: 200 - {"detail": "Artifact deleted"}

Upload Artifact from File

POST /artifacts/upload

Upload a document as a new artifact. Uses multipart/form-data.

Query Parameters:

Param	Type	Required	Description
`title`	`string`	Yes	Artifact title
`domain`	`string`	Yes	Domain classification
`agent_id`	`string`	No	Associated agent
`price_tokens`	`integer`	No	Subscription cost (default: 0)
`per_query_tokens`	`integer`	No	Per-query cost (default: 0)

Form Data:

Field	Type	Description
`file`	`binary`	File to upload (max 20 MB)

Response: 201 - ArtifactResponse

curl -X POST "https://api.projectkate.com/artifacts/upload?title=My+Guide&domain=general" \
  -H "x-api-key: your-api-key" \
  -F "file=@./guide.pdf"

Generate Cover

POST /artifacts/{artifact_id}/generate-cover

Generate the artifact's cover (public summary). Returns a task ID for polling.

Query Parameters:

Param	Type	Default	Description
`force`	`boolean`	`false`	Regenerate even if cover exists

Response: 202 - {"task_id": "..."}

Poll Cover Status

GET /artifacts/{artifact_id}/generate-cover/status/{task_id}

Response: 200 - {"status": "pending|completed|failed", ...}

Publish Artifact

POST /artifacts/{artifact_id}/publish

Publish the artifact. Auto-generates cover if not already done.

Response: 200 - ArtifactResponse (status → pending_review)

Analyze Coverage

POST /artifacts/{artifact_id}/analyze-coverage

Start asynchronous topic coverage analysis.

Response: 202 - {"task_id": "..."}

Poll Coverage Status

GET /artifacts/{artifact_id}/analyze-coverage/status/{task_id}

Response: 200 - {"status": "pending|completed|failed", ...}

Get Artifact Analytics

GET /artifacts/{artifact_id}/analytics

Response: 200

{
  "subscriber_count": 12,
  "total_queries": 340,
  "tokens_earned": 8500
}

Browse Listed Artifacts

GET /marketplace/artifacts

Browse artifacts that are published and available.

Query Parameters:

Param	Type	Default	Description
`domain`	`string`	-	Filter by domain
`min_quality`	`float`	-	Minimum quality score
`max_price`	`integer`	-	Maximum subscription price
`limit`	`integer`	`20`	Max results
`offset`	`integer`	`0`	Pagination offset

Response: 200 - ArtifactResponse[]

Extract from Agent

Start Async Extraction

POST /artifacts/extract-from-agent/{agent_id}/start

Query/Body Parameters:

Param	Type	Default	Description
`title`	`string`	-	Custom artifact title
`domain`	`string`	-	Domain classification
`price_tokens`	`integer`	`0`	Subscription cost
`per_query_tokens`	`integer`	`0`	Per-query cost

Response: 202 - {"task_id": "..."}

Poll Extraction Status

GET /artifacts/extract-from-agent/{agent_id}/status/{task_id}

Response: 200 - {"status": "pending|completed|failed", ...}

Artifacts API

On this page