Skip to content
HTTP API

Docs contents

Business and custom data

Connect an HTTP JSON API

Poll an allowed HTTPS API with GET, or a fixed read-only JSON POST, and show the values it returns on a dashboard.

You’ll have

Revenue and attainment from an API your team runs: a Custom block showing 124500 EUR as a hero number and another showing 83% as a bar, checked every five minutes.

You’ll need
  • Denframe installed and running: macOS, Windows or Home Assistant.
  • An API reachable from the Denframe host over public HTTPS that returns a small JSON response.
  • Administrator access to the host’s startup configuration, and the API’s read credential if it needs one.
  • An existing API that matches the example response below. api.example.com is a placeholder, not a working service.

Follow these steps in your own Denframe. This website never connects to your household, your accounts or your devices, and never asks for your credentials.

  1. Allow the API host

    Add the API hostname to DENFRAME_CUSTOM_BLOCK_HOSTS in the environment that starts Denframe, keeping any existing comma-separated entries, then restart the host. Use a hostname without a scheme or path. For a host started from a shell, the example below sets the variable; a service or container needs the equivalent deployment setting.

    Host environment example
    export DENFRAME_CUSTOM_BLOCK_HOSTS="api.example.com"

    The HTTP connection rejects private-network destinations, ports other than 443 and redirects, and the allowlist does not make a private address eligible. For local Home Assistant data, use the native Home Assistant connection.

  2. Open the HTTP API connection

    In Studio, open Sources, then Custom. Choose Add a custom source; the sheet asks where the data comes from.

    Choose HTTP API.

  3. Describe the request

    On the Connect stage, set Name to Sales summary. Set API address (HTTPS) to your endpoint, for example https://api.example.com/dashboard/summary, and select GET.

    Under Authentication, select Bearer token and enter the API token in Token or API key. If the service expects an API key instead, choose API key and set API key header to its header name, such as X-API-Key. Keep credentials out of the address and the request body.

    Set Check every (seconds) to 300.

    For an API that documents a read-only JSON query, select POST JSON instead and enter its exact supported body in JSON request body. The example assumes your own API implements these fields; aggregation happens upstream.

    Example POST body for a service you control
    {
  "report": "sales_summary",
  "region": "north",
  "metrics": ["revenue", "attainment_pct"]
}

    Testing sends one POST, and Denframe doesn’t automatically retry a POST within the same refresh.

  4. Test the connection

    Choose Test connection. It makes one request but does not create or attach a source. Your API should return the JSON below.

    Example API response · JSON
    {
  "revenue": 124500,
  "attainment_pct": 83,
  "currency": "EUR"
}

    The sheet moves to Choose data. Choose fields from the sample within ten minutes; if it expires, test again.

  5. Choose the values

    Set Display name to Revenue. Edit the existing field: keep Value type as Metric, choose /revenue in Available fields (or type it under Advanced field path), and set Label to Revenue and Unit to EUR. Under Presentation, select Hero number. Don’t add an extra field or leave the default /value path.

    Choose Add another value and name it Attainment. Change its existing field’s Value type to Range, choose /attainment_pct in Available fields, and set Label to Attainment, Minimum to 0, Maximum to 100 and Unit to %. Then select Bars.

    Give each value exactly one field, and keep the values separate so they can fill different blocks.

  6. Preview and add it to a dashboard

    Choose Preview selected values. Check that Revenue shows 124500 EUR and Attainment shows 83%. Pick the value in Value to show and look at it in both TV 16:9 and Portrait.

    Under Show on, tick an eligible dashboard and choose Add source. If you started from a Custom block selected in Studio, that exact block is updated; otherwise the connection adds a new block.

    To show the second value, add or select another Custom block in Studio and choose this existing source and its other value. The first block keeps its own value.

    A dashboard’s audience must permit the value you attach. Denframe never broadens the audience for you; change it in Studio first if the value is hidden.

  7. Check it worked

    The dashboard shows Revenue as 124500 EUR and Attainment as an 83% bar, and the source’s card on the Custom page reads HTTP API · selected values.

    To change the request later, open the source and choose Edit connection and data. Several values share one request, so a change affects every block that shows them; use Create a separate source for a different request.

    Modern: an editorial dashboard with a clock, agenda, forecast and headlines. Rendered by Denframe with sample data.

If it doesn’t work

Host is not allowed

Check the startup environment, restart Denframe, and use the hostname of the final HTTPS endpoint.

401 or 403

Replace the credential and check the API account can read the resource. Don’t put Authorization in a custom header row; use Authentication.

Invalid response or missing fields

Return application/json without compression, keep the response within 128 KiB, and match the exact field paths and types. Arrays use an index, such as /rows/0/revenue.

Changes affect another block

Several values share one request. Edit their mappings carefully, or use Create a separate source for a different request.

Related guides