API reference
Base URL https://api.frontpagely.com/v1. All requests need Authorization: Bearer <key>; bodies are JSON. Generated from the OpenAPI spec.
- GET /v1/tracked_entities: List tracked entities
- POST /v1/tracked_entities: Create a tracked entity
- GET /v1/tracked_entities/{id}: Retrieve a tracked entity
- PATCH /v1/tracked_entities/{id}: Update a tracked entity
- DELETE /v1/tracked_entities/{id}: Delete a tracked entity
- GET /v1/webhook_endpoints: List webhook endpoints
- POST /v1/webhook_endpoints: Create a webhook endpoint
- GET /v1/webhook_endpoints/{id}: Retrieve a webhook endpoint
- PATCH /v1/webhook_endpoints/{id}: Update a webhook endpoint
- DELETE /v1/webhook_endpoints/{id}: Delete a webhook endpoint
- POST /v1/webhook_endpoints/{id}/rotate: Rotate a webhook signing secret
- GET /v1/runs: List measurement runs
- GET /v1/visibility: List visibility snapshots
- GET /v1/widget: Read the plugin widget snapshot
GET /v1/tracked_entities
List tracked entities. Returns a paginated list of the team's tracked entities. Requires the entities:read scope.
Parameters
| Name | In | Description |
|---|---|---|
limit | query | Page size. 1–100. Defaults to 25. |
starting_after | query | Cursor for forward pagination. Pass the id of the last
item from the previous page to fetch the next page.
|
ending_before | query | Cursor for backward pagination. Pass the id of the first
item from the current page to fetch the previous page.
|
Response 200
A page of tracked entities. Each item in data:
| Field | Type | Description |
|---|---|---|
object | string | One of: tracked_entity. |
id | string | |
name | string | |
domain | string | |
created_at | string | |
updated_at | string |
Errors: 401. See error codes.
POST /v1/tracked_entities
Create a tracked entity. Creates a new tracked entity. Requires the entities:write scope.
Request body (JSON)
| Field | Type | Description |
|---|---|---|
name required | string | Display name of the brand |
domain | string | Primary domain for the entity |
Response 201
The created tracked entity.
| Field | Type | Description |
|---|---|---|
object | string | One of: tracked_entity. |
id | string | |
name | string | |
domain | string | |
created_at | string | |
updated_at | string |
Errors: 400, 401. See error codes.
GET /v1/tracked_entities/{id}
Retrieve a tracked entity. Returns a single tracked entity by id. Requires the entities:read scope.
Parameters
| Name | In | Description |
|---|---|---|
id required | path | A tracked-entity id, prefixed with ent_. |
Response 200
The tracked entity.
| Field | Type | Description |
|---|---|---|
object | string | One of: tracked_entity. |
id | string | |
name | string | |
domain | string | |
created_at | string | |
updated_at | string |
Errors: 401, 404. See error codes.
PATCH /v1/tracked_entities/{id}
Update a tracked entity. Updates mutable fields on a tracked entity. Requires the entities:write scope.
Parameters
| Name | In | Description |
|---|---|---|
id required | path | A tracked-entity id, prefixed with ent_. |
Request body (JSON)
| Field | Type | Description |
|---|---|---|
name required | string | Display name of the brand |
domain | string | Primary domain for the entity |
Response 200
The updated tracked entity.
| Field | Type | Description |
|---|---|---|
object | string | One of: tracked_entity. |
id | string | |
name | string | |
domain | string | |
created_at | string | |
updated_at | string |
Errors: 400, 401, 404. See error codes.
DELETE /v1/tracked_entities/{id}
Delete a tracked entity. Deletes a tracked entity. Requires the entities:write scope.
Parameters
| Name | In | Description |
|---|---|---|
id required | path | A tracked-entity id, prefixed with ent_. |
Response 204
Deleted. No content.
Errors: 401, 404. See error codes.
GET /v1/webhook_endpoints
List webhook endpoints. Returns the team's webhook endpoints. Requires the webhooks:read scope.
Parameters
| Name | In | Description |
|---|---|---|
limit | query | Page size. 1–100. Defaults to 25. |
starting_after | query | Cursor for forward pagination. Pass the id of the last
item from the previous page to fetch the next page.
|
ending_before | query | Cursor for backward pagination. Pass the id of the first
item from the current page to fetch the previous page.
|
Response 200
A page of webhook endpoints. Each item in data:
| Field | Type | Description |
|---|---|---|
object | string | One of: webhook_endpoint. |
id | string | |
url | string | |
events | array of string | |
signing_secret | string | Returned only on create and rotate. |
created_at | string |
Errors: 401. See error codes.
POST /v1/webhook_endpoints
Create a webhook endpoint. Registers a new webhook endpoint. Requires the webhooks:write scope.
Request body (JSON)
| Field | Type | Description |
|---|---|---|
url required | string | |
events required | array of string | Subscribed event types (see the webhooks.js EVENT_TYPES taxonomy). |
Response 201
The created webhook endpoint (includes the signing secret once).
| Field | Type | Description |
|---|---|---|
object | string | One of: webhook_endpoint. |
id | string | |
url | string | |
events | array of string | |
signing_secret | string | Returned only on create and rotate. |
created_at | string |
Errors: 400, 401. See error codes.
GET /v1/webhook_endpoints/{id}
Retrieve a webhook endpoint. Returns a single webhook endpoint. Requires the webhooks:read scope.
Parameters
| Name | In | Description |
|---|---|---|
id required | path | A webhook-endpoint id, prefixed with whe_. |
Response 200
The webhook endpoint.
| Field | Type | Description |
|---|---|---|
object | string | One of: webhook_endpoint. |
id | string | |
url | string | |
events | array of string | |
signing_secret | string | Returned only on create and rotate. |
created_at | string |
Errors: 401, 404. See error codes.
PATCH /v1/webhook_endpoints/{id}
Update a webhook endpoint. Updates the URL or subscribed events. Requires the webhooks:write scope.
Parameters
| Name | In | Description |
|---|---|---|
id required | path | A webhook-endpoint id, prefixed with whe_. |
Request body (JSON)
| Field | Type | Description |
|---|---|---|
url required | string | |
events required | array of string | Subscribed event types (see the webhooks.js EVENT_TYPES taxonomy). |
Response 200
The updated webhook endpoint.
| Field | Type | Description |
|---|---|---|
object | string | One of: webhook_endpoint. |
id | string | |
url | string | |
events | array of string | |
signing_secret | string | Returned only on create and rotate. |
created_at | string |
Errors: 400, 401, 404. See error codes.
DELETE /v1/webhook_endpoints/{id}
Delete a webhook endpoint. Deletes a webhook endpoint. Requires the webhooks:write scope.
Parameters
| Name | In | Description |
|---|---|---|
id required | path | A webhook-endpoint id, prefixed with whe_. |
Response 204
Deleted. No content.
Errors: 401, 404. See error codes.
POST /v1/webhook_endpoints/{id}/rotate
Rotate a webhook signing secret. Generates a new signing secret for the endpoint and returns it once. Requires the webhooks:write scope.
Parameters
| Name | In | Description |
|---|---|---|
id required | path | A webhook-endpoint id, prefixed with whe_. |
Response 200
The endpoint with its new signing secret.
| Field | Type | Description |
|---|---|---|
object | string | One of: webhook_endpoint. |
id | string | |
url | string | |
events | array of string | |
signing_secret | string | Returned only on create and rotate. |
created_at | string |
Errors: 401, 404. See error codes.
GET /v1/runs
List measurement runs. Returns a paginated list of measurement runs for one tracked entity, newest first. The tracked_entity_id query parameter is required and must reference an entity the key can read. Requires the entities:read scope.
Parameters
| Name | In | Description |
|---|---|---|
tracked_entity_id required | query | A tracked-entity id, prefixed with ent_. The entity must be readable by the key. |
limit | query | Page size. 1–100. Defaults to 25. |
starting_after | query | Cursor for forward pagination. Pass the id of the last
item from the previous page to fetch the next page.
|
status | query | Optional filter on run status. |
Response 200
A page of runs. Each item in data:
| Field | Type | Description |
|---|---|---|
object | string | One of: run. |
id | string | |
tracked_entity_id | string | |
trigger | string | null | What initiated the run (e.g. schedule |
status | string | null | Lifecycle status of the run. |
engines_requested | array of string | The engines this run was planned to query. |
samples_per_prompt | integer | null | |
started_at | string | null | |
completed_at | string | null | |
created_at | string |
Errors: 400, 401, 404. See error codes.
GET /v1/visibility
List visibility snapshots. Returns a paginated list of visibility snapshots (the aggregated SeenRate trend record) for one tracked entity, newest first. The tracked_entity_id query parameter is required; optionally filter to a single run with run_id. Requires the entities:read scope.
Parameters
| Name | In | Description |
|---|---|---|
tracked_entity_id required | query | A tracked-entity id, prefixed with ent_. The entity must be readable by the key. |
run_id | query | Optional filter to the snapshot(s) for one run, prefixed with run_. |
limit | query | Page size. 1–100. Defaults to 25. |
starting_after | query | Cursor for forward pagination. Pass the id of the last
item from the previous page to fetch the next page.
|
Response 200
A page of visibility snapshots. Each item in data:
| Field | Type | Description |
|---|---|---|
object | string | One of: visibility_snapshot. |
id | string | |
tracked_entity_id | string | |
run_id | string | |
seenrate | number | 0–100 headline SeenRate. |
per_engine_scores | object | Per-engine SeenRate, e.g. { chatgpt 62, perplexity 56, claude 38 }. |
components | object | The M/P/SV/C/O component scores (0–1). |
share_of_voice | number | null | 0–1 share of voice. |
n_effective | number | |
engines_run | array of string | The engines that actually ran (drives §4.3 comparability). |
trust | object | null | Per-engine parser trust, or null. |
directional | object | null | Directional flags (e.g. engines, location_directional). |
score_methodology_version | integer | FK to score_methodology_versions |
created_at | string |
Errors: 400, 401, 404. See error codes.
GET /v1/widget
Read the plugin widget snapshot. Returns the latest headline metrics for the single tracked entity a plugin key (pk_…) is bound to: SeenRate, per-engine scores, share of voice, which engines ran, and the measurement time. It is a strict subset of /visibility (a short headline trend, no cursors or methodology internals), plus a confidence label and the top open fixes for the plugin's admin page. This endpoint is reachable only by a plugin-scoped read-only key, which carries the widget:read scope and no other. Unlike the rest of the API it is not gated on a Pro plan, so a connected WordPress plugin on a Starter-tier account can still populate its wp-admin widget. The entity is fixed at mint time (bound to the key): there is no entity query parameter, and no other key type can call this route.
Response 200
The entity's latest headline widget metrics.
| Field | Type | Description |
|---|---|---|
object | string | One of: widget. |
tracked_entity_id | string | |
name | string | |
seenrate | number | null | 0–100 headline SeenRate. |
per_engine_scores | object | |
share_of_voice | number | null | 0–1. |
engines_run | array of string | |
measured_at | string | null | |
confidence | string | null | Directional when the latest run had too few usable answers to be confident. One of: confirmed, directional. |
trend | array of object | Up to 12 recent headline points, oldest first. |
open_fixes | integer | Open items in the entity's fix plan. |
top_fixes | array of object | Up to 3 open fixes, most important first. |
Errors: 401, 403, 404. See error codes.
Questions about the API? Contact support, and include the request_id from any error.