REST API reference for the Cognitia data marketplace. All endpoints require an active business account.
All marketplace API endpoints require authentication via a business API key. Generate one from your dashboard under Balance & API → API Key.
Request Header
Authorization: Bearer cog_biz_xxxxxxxxxxxxxxxxAPI keys are shown only once at generation time. Store them securely. You can revoke and regenerate keys from the dashboard.
| Tier | Price per Query | Consent Required | Data |
|---|---|---|---|
| Insights | $0.01 | No (global enrollment) | Anonymized & pseudonymized entities, signals, facts |
| Personalized | $0.10 | Yes (per-user, per-PII field) | Selective PII + behavioral data |
/api/marketplace/previewPublic marketplace overview with provider counts, pricing, and sample outputs. No authentication required.
Authentication
None (public endpoint)
Sample Response
{
"marketplace": {
"totalProviders": 142,
"insightsProviders": 142,
"personalizedProviders": 28,
"distributions": {
"entityTypes": {
"person": 45,
"organization": 32,
"location": 28
},
"signalCategories": {
"communication": 60,
"browsing": 45
}
}
},
"pricing": {
"insights": {
"pricePerQuery": 0.01
},
"personalized": {
"pricePerQuery": 0.1
}
}
}/api/marketplace/discoverDiscover data providers with filtering by tier, entity types, signal categories, and minimum data counts.
Authentication
Bearer cog_biz_... API key or authenticated session
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tier | string | No | "insights" or "personalized". Defaults to insights. |
limit | number | No | Max results (1-100, default 20) |
offset | number | No | Pagination offset (default 0) |
entity_types | string | No | Comma-separated entity types to filter by |
signal_categories | string | No | Comma-separated signal categories to filter by |
min_entity_count | number | No | Minimum entity count for providers |
Sample Response
{
"success": true,
"totalResults": 2,
"offset": 0,
"limit": 20,
"providers": [
{
"listingId": "uuid-1",
"userId": "user-abc...",
"tiers": {
"insights": true,
"personalized": false
},
"metadata": {
"entityCount": 156,
"signalCount": 89,
"factCount": 42,
"topEntityTypes": [
"person",
"organization"
],
"topSignalCategories": [
"communication",
"browsing"
]
},
"lastUpdated": "2026-04-10T05:00:00Z"
}
]
}/api/marketplace/aggregate-queryRun aggregate queries across all enrolled providers. Fast mode uses pre-computed metadata; Premium runs per-provider agent loops.
Authentication
Bearer cog_biz_... API key or authenticated session
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
mode | string | Yes | "fast" (free) or "premium" (billed per provider at Insights rate) |
data_layer | string | No | Required for premium: "knowledge_graph", "behavioral_signals", or "temporal_facts" |
max_providers | number | No | Premium only: max providers to query (default 100, max 1000) |
Sample Response
{
"success": true,
"mode": "fast",
"totalProviders": 142,
"avgEntityCount": 87,
"avgSignalCount": 45,
"avgFactCount": 22,
"topEntityTypes": {
"person": 120,
"organization": 85
},
"topSignalCategories": {
"communication": 95,
"browsing": 70
}
}/api/marketplace/personalized-queryQuery a specific user's data with Personalized tier access. Requires prior consent approval from the target user.
Authentication
Bearer cog_biz_... API key
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
target_user_id | string | Yes | The user ID to query |
query | string | Yes | Natural language query to run against the user's data |
data_layer | string | Yes | "knowledge_graph", "behavioral_signals", or "temporal_facts" |
Sample Response
{
"success": true,
"tier": "personalized",
"transactionId": "txn-uuid",
"costUsd": 0.1,
"result": {
"entities": [
{
"name": "John Doe",
"type": "person",
"properties": {
"email": "john@example.com",
"city": "San Francisco"
}
}
],
"piiIncluded": [
"email",
"full_name",
"city_region"
]
}
}/api/marketplace/aggregate-queryShortcut for fast-mode aggregate stats. Equivalent to POST with mode="fast".
Same authentication and response as POST with mode="fast".
| HTTP Status | Meaning |
|---|---|
| 400 | Invalid request parameters or missing required fields |
| 401 | Missing or invalid API key / session |
| 402 | Insufficient balance to complete the query |
| 403 | Business account inactive or consent not granted |
| 404 | Target user or listing not found |
| 409 | Duplicate consent request already pending |
| 500 | Internal server error |
Cognitia Marketplace API v1 — Questions? Contact support or visit the Data Platform