Bots API

Open HTTP API for privacy-safe Discord Bot Shop metrics: installs and inference usage as numbers only. No message content, no Discord user IDs, and no guild identity in responses.

Use this to audit how a public character is used after install (including future royalty accounting). It does not grant ownership of characters or replace Venice’s character catalog.

Related product docs: Bots · AiSpace Bot Shop

Base URL

https://aispace.bot

All routes below are on the AiSpace web app origin (not x402.aispace.bot).

Authentication

None. Endpoints are public. Anyone who knows a character slug or Venice author id can read aggregates.

Privacy

Returned fields are aggregates only:

Install counts (not which servers)
Message counts, prompt/completion tokens, credits charged
Venice author (anonymized creator id) when known

Never returned: prompts, replies, Discord user ids, guild ids, guild names.

GET `/api/discord-bot-usage`

Exactly one of slug or author is required.

Query	Behavior
`slug`	One character’s lifetime aggregates
`author`	Complete list of that author’s characters with metrics (paginated)
both / neither	`400`

By slug

GET /api/discord-bot-usage?slug=alan-watts

Example response:

{
  "slug": "alan-watts",
  "author": "…",
  "installCount": 12,
  "messages": 1000,
  "promptTokens": 120000,
  "completionTokens": 80000,
  "creditsCharged": 45000,
  "updatedAt": "2026-08-09T10:00:00.000Z"
}

Unused characters return zeros for counters (and author when resolvable from the catalog), not a hard 404.

Field	Meaning
`installCount`	Distinct Discord server installs recorded for this slug
`messages`	Consume events (chat turns) attributed to this slug
`promptTokens` / `completionTokens`	Lifetime token meters
`creditsCharged`	Lifetime guild credits debited for this slug (best royalty base)
`author`	Venice anonymized author id (ownership join key; not a payout address)

By author (complete list)

For creators with many bots (including 100+):

GET /api/discord-bot-usage?author=AUTHOR_ID&limit=50&offset=0

Param	Default	Notes
`limit`	`50`	Max `100` per page
`offset`	`0`	Skip this many rows

Example response:

{
  "author": "AUTHOR_ID",
  "total": 105,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "slug": "…",
      "author": "AUTHOR_ID",
      "installCount": 3,
      "messages": 10,
      "promptTokens": 100,
      "completionTokens": 50,
      "creditsCharged": 20,
      "updatedAt": "…"
    }
  ]
}

total is the full set size; paginate with offset until exhausted (not capped at 100 bots overall).
Rows are ordered by creditsCharged descending, then slug.
Includes characters that were installed only (zero messages) when stamped with that author.

How meters are written

Event	What is recorded
Discord unlock redeem (install)	Install roster: server × slug × free/paid × author
Guild credit consume (each chat turn)	+messages, +tokens, +creditsCharged on that slug

The Discord platform must send slug on every consume call. AiSpace requires it (400 if missing).

Agent API (x402) — paid Venice-equivalent inference marketplace (separate product)
Venice characters catalog — Venice docs / Postman (GET /characters, includes author)

Notes for royalties (future)

Prefer rolling up creditsCharged (and optionally tokens) by author.
author is an anonymized Venice id, not a wallet. Payout mapping is out of band / future.
Install fee on Bot Shop is a facilitation fee, not a sale of the bot IP — see Bot Shop and Terms.

Pricing Errors