GET
datasets
User API Service tier
Datasets in the caller's org, one summary row each.
Query: q (name / description contains), source_kind, limit, offset, full=1 for the complete dataset payload per row.
URL
User API https://analytics.mattering.io/api/user/v1/datasets
Service tier https://analytics.mattering.io/api/internal/v1/datasets
Query parameters
Name Default
fullnone qnone searchnone source_kindnone
Pagination
Accepts limit and offset. The response meta carries total, limit and offset.
Responses
200 data and meta envelope
{
"data": [
"..."
],
"meta": {
"total": 0,
"limit": 0,
"offset": 0,
"returned": 0,
"has_more": true,
"view": "full"
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Example
User API Service tier
curl -X GET "https://analytics.mattering.io/api/user/v1/datasets?full=...&q=...&search=..." \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://analytics.mattering.io/api/internal/v1/datasets?full=...&q=...&search=..." \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: AnalyticsCore/api.py (api.list_datasets)
GET
datasets/{public_id}
User API Service tier
Read one of the datasets by id. derived from route
URL
User API https://analytics.mattering.io/api/user/v1/datasets/{public_id}
Service tier https://analytics.mattering.io/api/internal/v1/datasets/{public_id}
Path parameters
Responses
200 data and meta envelope
{
"data": "..."
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Example
User API Service tier
curl -X GET "https://analytics.mattering.io/api/user/v1/datasets/PUBLIC_ID" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://analytics.mattering.io/api/internal/v1/datasets/PUBLIC_ID" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: AnalyticsCore/api.py (api.get_dataset)
POST
datasets/{public_id} /publish
User API Service tier
Materialize a dataset's shaped rows into a Data Studio datatable.
The loop-closing half of the integration: an agent can shape data here and hand it to automations as datatable entries to trigger on. Append-only.
Body: {"datatable_id": "<uuid>"} or {"create_name": "<name>"}.
This read is not paginated. It returns at most 20 rows and does not report a total, so a result of exactly 20 may be truncated.
URL
User API https://analytics.mattering.io/api/user/v1/datasets/{public_id} /publish
Service tier https://analytics.mattering.io/api/internal/v1/datasets/{public_id} /publish
Path parameters
Body keys (JSON)
Key Required Default
create_nameoptional or conditional none datatable_idoptional or conditional none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"datatable_id": "...",
"created": true,
"partial": true,
"rejected": 0,
"rejected_sample": "..."
},
"meta": {
"errors": [
"..."
],
"error_count": 0
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 invalid_json400 missing_field409 nothing_to_publish502 publish_failed
Example
User API Service tier
curl -X POST "https://analytics.mattering.io/api/user/v1/datasets/PUBLIC_ID/publish" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"create_name": "...",
"datatable_id": "..."
}' curl -X POST "https://analytics.mattering.io/api/internal/v1/datasets/PUBLIC_ID/publish" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"create_name": "...",
"datatable_id": "..."
}'
Source: AnalyticsCore/api.py (api.publish_dataset)
POST
datasets/{public_id} /refresh
User API Service tier
POST to datasets/{public_id}/refresh. derived from route
URL
User API https://analytics.mattering.io/api/user/v1/datasets/{public_id} /refresh
Service tier https://analytics.mattering.io/api/internal/v1/datasets/{public_id} /refresh
Path parameters
Query parameters
Name Default
fullnone schemanone
Responses
200 data and meta envelope
{
"data": {
"row_count": 0,
"fetched_at": "2026-01-01T00:00:00Z",
"duration_ms": 0,
"column_count": 0,
"schema": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
502 refresh_failed
Example
User API Service tier
curl -X POST "https://analytics.mattering.io/api/user/v1/datasets/PUBLIC_ID/refresh" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X POST "https://analytics.mattering.io/api/internal/v1/datasets/PUBLIC_ID/refresh" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: AnalyticsCore/api.py (api.refresh_dataset)
GET
datasets/{public_id} /rows
User API Service tier
Materialized rows for a dataset, honoring its refresh policy.
URL
User API https://analytics.mattering.io/api/user/v1/datasets/{public_id} /rows
Service tier https://analytics.mattering.io/api/internal/v1/datasets/{public_id} /rows
Path parameters
Query parameters
Name Default
columnsnone fieldsnone schemanone
Pagination
Accepts limit and offset. The response meta carries total, limit and offset.
Responses
200 data and meta envelope
{
"data": {
"rows": [
"..."
],
"schema": [
"..."
]
},
"meta": {
"total": 0,
"limit": 0,
"offset": 0,
"returned": 0,
"has_more": true,
"columns": [
"..."
],
"fetched_at": "2026-01-01T00:00:00Z",
"stale_error": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Example
User API Service tier
curl -X GET "https://analytics.mattering.io/api/user/v1/datasets/PUBLIC_ID/rows?columns=...&fields=...&schema=..." \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://analytics.mattering.io/api/internal/v1/datasets/PUBLIC_ID/rows?columns=...&fields=...&schema=..." \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: AnalyticsCore/api.py (api.dataset_rows)