Hub API Reference - ezForge AI

Overview

The Hub API lets you manage consumer-facing Hub API keys and query per-listing analytics. All endpoints require a session token — pass the authenticated user’s Bearer token in the Authorization header. Hub API keys themselves (for agent-developer access to Hub discovery endpoints) are a separate credential type; see Create API key below. Base URL: https://ezforge.ai Authentication: All endpoints require Authorization: Bearer <user-token>.

Dedicated pages provide deeper coverage of each area: API Keys (security model, header usage, deprecated endpoint migration) and Listing Analytics (tier comparison table, metric definitions).

API keys

Hub API keys allow agent developers to call Hub discovery and data endpoints. Keys are tier-gated with daily request limits:

Tier	Daily limit
`explorer`	100 requests/day
`builder`	10,000 requests/day
`partner`	100,000 requests/day

Create API key

POST /api/v1/hub/api-keys

Creates a new Hub API key for the authenticated user. The raw key is returned exactly once — store it immediately; it cannot be retrieved again. Request body:

{
  "tier": "explorer"
}

Field	Type	Required	Description
`tier`	string	—	Key tier: `explorer`, `builder`, or `partner`. Defaults to `explorer`.

Response 201:

{
  "data": {
    "key": "hub_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "meta": {
      "id": "01JQXYZ0000000000000000000",
      "userId": "01JQABC0000000000000000000",
      "keyPrefix": "hub_live_xxxxxxx",
      "tier": "explorer",
      "dailyRequestCount": 0,
      "lastRequestAt": null,
      "createdAt": "2026-05-15T10:00:00.000Z",
      "revokedAt": null
    }
  }
}

The key field is returned only once, at creation time. Store it securely — it cannot be retrieved again.

Response fields (meta):

Field	Type	Description
`id`	string	ULID key identifier
`userId`	string	ULID of the owning user
`keyPrefix`	string	First 16 characters of the key (safe to display)
`tier`	string	Key tier: `explorer`, `builder`, or `partner`
`dailyRequestCount`	integer	Requests made today (resets UTC midnight)
`lastRequestAt`	ISO 8601 or `null`	Timestamp of the most recent request
`createdAt`	ISO 8601	Key creation timestamp
`revokedAt`	ISO 8601 or `null`	Set when the key is revoked; `null` for active keys

Error responses:

Status	Code	Condition
401	`unauthorized`	Missing or invalid session token
422	`validation_error`	`tier` is not one of `explorer`, `builder`, `partner`
429	`rate_limited`	IP rate limit exceeded (`Retry-After` reflects seconds until window reset, ≤ 60)
503	`service_unavailable`	Rate-limit service temporarily unavailable

List API keys

GET /api/v1/hub/api-keys

Returns all active (non-revoked) Hub API keys for the authenticated user, ordered oldest-first. Returns up to 100 keys. Raw key values are never returned. Response 200:

{
  "data": [
    {
      "id": "01JQXYZ0000000000000000000",
      "userId": "01JQABC0000000000000000000",
      "keyPrefix": "hub_live_xxxxxxx",
      "tier": "builder",
      "dailyRequestCount": 42,
      "lastRequestAt": "2026-05-15T09:14:00.000Z",
      "createdAt": "2026-03-01T08:00:00.000Z",
      "revokedAt": null
    }
  ]
}

Error responses:

Status	Code	Condition
401	`unauthorized`	Missing or invalid session token
429	`rate_limited`	IP rate limit exceeded (`Retry-After` reflects seconds until window reset, ≤ 60)
503	`service_unavailable`	Rate-limit service temporarily unavailable

Revoke API key

DELETE /api/v1/hub/api-keys/:id

Immediately revokes a Hub API key. Any subsequent requests using this key will receive a 401. Revocation cannot be undone. Path parameters:

Parameter	Type	Description
`id`	string	ULID of the key to revoke

Response 204: No content. Error responses:

Status	Code	Condition
401	`unauthorized`	Missing or invalid session token
404	`not_found`	Key not found or not owned by the authenticated user
409	`conflict`	Key is already revoked
429	`rate_limited`	IP rate limit exceeded (`Retry-After` reflects seconds until window reset, ≤ 60)
503	`service_unavailable`	Rate-limit service temporarily unavailable

Analytics

Get listing analytics

GET /api/v1/hub/analytics/listings/:id

Returns analytics for a Hub listing. The response shape is gated by the listing’s tier — callers receive only the fields their tier makes available. Only the listing owner can access this endpoint. Path parameters:

Parameter	Type	Description
`id`	string	26-character ULID of the listing

Query parameters:

Parameter	Type	Default	Description
`period`	string	`30d`	Reporting window: `7d`, `30d`, or `90d`

Response 200 — Basic tier:

{
  "data": {
    "tier": "basic",
    "period": "30d",
    "view_count": 312
  }
}

Response 200 — Featured tier:

{
  "data": {
    "tier": "featured",
    "period": "30d",
    "view_count": 312,
    "click_count": 87,
    "click_through_rate": 27.88
  }
}

Response 200 — Premium tier:

{
  "data": {
    "tier": "premium",
    "period": "30d",
    "view_count": 312,
    "click_count": 87,
    "click_through_rate": 27.88,
    "search_impressions": 1540,
    "referral_clicks": 34,
    "conversion_rate": 3.21
  }
}

Response fields:

Field	Type	Tiers	Description
`tier`	string	all	Listing tier used to gate this response: `basic`, `featured`, or `premium`
`period`	string	all	Reporting window reflected back: `7d`, `30d`, or `90d`
`view_count`	integer	all	Total listing views in the period
`click_count`	integer	Featured, Premium	Total click-throughs from search results
`click_through_rate`	number	Featured, Premium	`click_count / view_count × 100`, rounded to 2 decimal places
`search_impressions`	integer	Premium	Times the listing appeared in search results
`referral_clicks`	integer	Premium	Referral-link interactions originating from Hub discovery
`conversion_rate`	number	Premium	`transactions / view_count × 100`, rounded to 2 decimal places

Error responses:

Status	Code	Condition
400	`invalid_input`	`id` is not a valid 26-character ULID, or `period` is not `7d`, `30d`, or `90d`
401	`unauthorized`	Missing or invalid session token
403	`forbidden`	Authenticated user does not own this listing
404	`not_found`	Listing not found
429	`rate_limited`	IP rate limit exceeded (`Retry-After` reflects seconds until window reset, ≤ 60)
503	`service_unavailable`	Rate-limit service temporarily unavailable

Deprecated endpoints

/api/v1/hub/keys is deprecated. Use /api/v1/hub/api-keys for all new integrations. The /api/v1/hub/keys path will be sunset on 2028-01-01 and removed in a future release.

Responses from the deprecated path include the following headers to signal migration:

Deprecation: true
Link: </api/v1/hub/api-keys>; rel="successor-version"
Sunset: Sat, 01 Jan 2028 00:00:00 GMT

Deprecated path	Replacement
`POST /api/v1/hub/keys`	`POST /api/v1/hub/api-keys`
`GET /api/v1/hub/keys`	`GET /api/v1/hub/api-keys`
`DELETE /api/v1/hub/keys/:id`	`DELETE /api/v1/hub/api-keys/:id`

​Overview

​API keys

​Create API key

​List API keys

​Revoke API key

​Analytics

​Get listing analytics

​Deprecated endpoints

Overview

API keys

Create API key

List API keys

Revoke API key

Analytics

Get listing analytics

Deprecated endpoints