Analytics API

2 operations. Authentication, errors and pagination work as described in the REST API overview.

Record a client-side event (copy, share) for creator analytics

POST/api/v1/analytics/eventsToken optional

The browser beacon used by the web app. Always 204; events on prompts the caller cannot read are ignored.

Request body

recordAnalyticsEvent body fields
Name	Type	Description
`event`required	`"copy" \| "share_click"`
`ref`required	`string`

Responses: 204 OK400, 404, 429

Example

curl -X POST 'https://incantory.ai/api/v1/analytics/events' \
  -H "Authorization: Bearer $INCANTORY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"event":"copy","ref":"alice/haiku"}'

Daily analytics for one of your prompts

GET/api/v1/analytics/prompts/{owner}/{slug}Token required · scope read

Owner (or admin) only; anyone else gets 404. Daily rows from the hourly rollup (UTC days, zero-filled), totals, top referrer hosts and countries. format=csv downloads the daily rows. Counts are a floor: responses served from the CDN cache do not reach the origin.

getPromptAnalytics parameters
Name	Type	Description
`owner` pathrequired	`string`	Owner handle
`slug` pathrequired	`string`	Prompt slug
`from` query	`string`	First day, inclusive (UTC). Default: 29 days before `to`.
`to` query	`string`	Last day, inclusive (UTC). Default: today. Ranges are capped at 366 days.
`format` query	`"json" \| "csv"`	`csv` returns one row per day.

Responses: 200 OK400, 401, 403, 404, 429

Response fields

getPromptAnalytics response fields
Name	Type	Description
`scope`required	`object`
`from`required	`string`
`to`required	`string`
`totals`required	`object`
`days`required	`object[]`
`referrers`required	`object[]`	Top referrer hosts in the range
`countries`required	`object[]`	Top countries (ISO 3166-1 alpha-2, from Cloudflare)

Example

curl 'https://incantory.ai/api/v1/analytics/prompts/{owner}/{slug}' \
  -H "Authorization: Bearer $INCANTORY_TOKEN"