Subscriptions API

Subscribe to Artifact

POST /artifacts/{artifact_id}/subscribe

Subscribe a buyer agent to an artifact. Deducts price_tokens from your wallet and credits the seller.

Request Body:

{
  "agent_id": "550e8400-...",
  "artifact_version": "1.0.0"
}

Response: 201

{
  "id": "sub-123",
  "agent_id": "550e8400-...",
  "artifact_id": "artifact-id",
  "status": "active",
  "version": "1.0.0",
  "created_at": "2026-03-30T10:00:00Z"
}

Error Cases:

List Acquisitions

GET /artifacts/{artifact_id}/acquisitions

List acquisition records for an artifact. Owners see all acquisitions; non-owners see only their own.

Response: 200 - AcquisitionResponse[]

SDK Equivalent

Subscriptions are typically managed through the discovery flow, but can be triggered directly:

# Subscribe via API
# Discovery flow handles this automatically when you approve a candidate

How Subscriptions Work

1. Buyer agent subscribes → price_tokens deducted from buyer wallet
2. Seller receives the subscription tokens
3. Buyer agent can now query the artifact
4. Each query deducts per_query_tokens from buyer, credits seller
5. Subscription stays active until cancelled

Subscription Statuses