canonical: https://jentic.com/apis/cyfe.com/cyfe

# Cyfe Push API

Cyfe is a business dashboard platform that aggregates KPIs from marketing, sales, finance, and product systems into a single view. The Push API exposes one POST endpoint for streaming custom metrics into a Cyfe widget, identified by a per-widget URL token. It is the integration surface used when an internal system, script, or AI agent needs to render its own data in a Cyfe dashboard alongside the platform's prebuilt connectors.

## For AI agents

Push custom metric data points into a Cyfe dashboard widget so an agent's own measurements show up in a shared business dashboard.

## Scope

Does not handle dashboard creation, widget configuration, or read-back of stored data - use for pushing custom metric values into existing Cyfe widgets only.

## Capabilities

- Push a single time-series data point into a Cyfe custom widget by widget ID
- Stream batch metric updates as JSON payloads to keep a dashboard widget current
- Backfill historical data into a Cyfe widget by including explicit date fields in the payload
- Pipe agent-generated KPIs into an existing Cyfe dashboard without writing a Cyfe connector
- Treat the per-widget URL token as a scoped credential to avoid sharing account-level secrets

## Use cases

### Custom KPI Dashboard Feed

A team running a Cyfe dashboard for executives wants to add a metric that is not covered by Cyfe's prebuilt connectors, such as agent-completed support tickets or model-cost-per-task. They configure a custom widget, take its push URL, and have a scheduled agent POST the latest value once an hour. The widget renders alongside the platform's native integrations without any custom dashboard code.

Example prompt: POST {"data":[{"Date":"2026-06-10","Tickets":42}]} to `/api/push/{widget_id}` once per hour.

### Historical Backfill Into a New Widget

When a team adds a new Cyfe widget mid-quarter, they need the chart to start with historical context rather than a single fresh data point. The Push API accepts an array of dated entries, so an agent can iterate through the past 30 or 90 days of stored values and POST them in one or two requests, populating the widget's history.

Example prompt: Build a JSON array of 30 daily values from the data warehouse and POST it to `/api/push/{widget_id}` as a single request.

### Agent-Driven Operational Metrics

An AI agent supervising a fleet of automation jobs publishes its own observability metrics to a Cyfe widget so non-technical stakeholders can see throughput and success rate without opening logs. The agent reads its own state, computes the metric, and pushes the value, turning agent activity into a first-class dashboard tile.

Example prompt: Read the agent's task log for the last hour, compute success rate, and POST {"data":[{"Date":"NOW","SuccessRate":97.2}]} to `/api/push/{widget_id}.`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/push/{widget_id}` | Push data to a Cyfe custom dashboard widget |

## Key resources

- **Push** — Single endpoint for posting metric payloads to a custom widget

## Why Jentic

- **Setup:** Wiring the Cyfe Push API by hand means keeping each widget's push URL secret, formatting the metric payload, and posting it to the right widget yourself. Through Jentic you install once, import the Cyfe Push API from the API Directory, store the widget push URL once, and your agent calls it.
- **Permission scoping:** Cyfe puts the widget id in the URL path (`/api/push/{widget_id}`), so a rule can pin your agent to pushing values into one widget and nothing else. Pushing metrics is the only operation this API exposes, so the agent cannot read back or reconfigure the dashboard.
- **Credential handling:** Your Cyfe widget push URL is treated as a secret, stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'push a metric value to a Cyfe dashboard', and Jentic returns the Cyfe Push operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Geckoboard API** — Dashboard service with a similar push-based custom widget model and richer visualisation options.
- **Mixpanel API** — Product analytics events that can be aggregated and pushed into a Cyfe dashboard summary.
- **HubSpot Marketing Events API** — CRM and marketing event data to roll up into a Cyfe revenue or pipeline widget.

## FAQ

### What authentication does the Cyfe Push API use?

Cyfe's Push API uses a per-widget URL token rather than a global API key. Each custom widget has its own widget_id which is treated as a shared secret in the URL path. Through Jentic the widget URL is stored in the encrypted vault and surfaced to the agent as a scoped runtime credential, so the raw URL never lands in chat history.

### Can I push multiple data points in one Cyfe API call?

Yes. The `/api/push/{widget_id}` endpoint accepts an array under the data key, so you can send a batch of dated entries in a single POST. This is how historical backfill works when you add a new widget mid-quarter.

### What are the rate limits for the Cyfe Push API?

Cyfe does not document explicit rate limits for the Push API in the spec. The platform's published guidance is to push no more frequently than once per minute per widget; for higher-frequency telemetry, batch values into a single payload rather than firing many small requests.

### How do I publish an agent's KPI to Cyfe through Jentic?

Install pip install jentic and run an agent with the search query 'push data to a Cyfe dashboard widget'. Jentic returns the POST `/api/push/{widget_id}` operation with its input schema; the agent constructs the JSON payload (Date, plus one or more numeric fields) and calls execute.

### Can I read data back from a Cyfe widget through this API?

No. The Push API is write-only. There is no endpoint for retrieving widget contents, dashboards, or account metadata; the only operation exposed is POST `/api/push/{widget_id}.`

### Is the Cyfe Push API free?

Push API access is included with all paid Cyfe plans, including the entry-level Starter tier. Cyfe has historically offered a free tier with a small number of widgets which also includes Push API support, so single-widget integrations can run at no cost.

### Can I limit what my agent is allowed to do with the Cyfe Push API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which operations and credentials the agent may use. Cyfe puts the widget id in the URL path (POST `/api/push/{widget_id}`), so you can pin the agent to pushing values into one specific widget and nothing else. Pushing metrics is the only operation this API exposes, so the agent cannot read back stored data or reconfigure the dashboard.