Hodoflow / Developers
Sign in
Browse documentation
Help Center →
Browse API reference
JSON:API v1 stable

Create a widget

Create a new widget in the service account's workspace.

POST /api/json/v1/widgets

Access and behavior

Required scope
api_write
Authentication
Bearer token
Idempotency
supported
Operation ID
createWidget

Request headers

Header Presence Description
Authorization Required Short-lived service-account bearer token.
Accept Required JSON:API response media type.
Idempotency-Key Optional Makes an unsafe request replay-safe for the configured retention window (24 hours by default). Reusing a key with different request parameters returns 409.
Content-Type Required Request document media type.

Parameters

include

query · Optional

string

Relationship paths to include in the response

fields

query · Optional

object

Limits the response fields to only those listed for each type

Request body

application/vnd.api+json

Schema: object · Required

config

Optional

object | null

Type-specific configuration (columns, fields, aggregations, etc.)

data_model_id

Optional

string | null

Data model id accepted by this operation.

embed_filter_allowlist

Optional

array<string> | null

Filter dimensions a public embedder may override at runtime. Defaults to allowing time_range; clear the array to lock all filters.

filters

Optional

widget_filters-input-create-type | null

Author-baseline filter set (e.g. time-range constraint) layered with dashboard/runtime overlays at read time.

name

Required

string

Human-readable resource name.

organization_id

Optional

string | null

Organization that owns the resource.

source

Optional

enum: dashboard | library | null

Origin: :dashboard (inline, auto-cleaned) or :library (standalone)

type

Required

enum: line_chart | bar_chart | map_chart | table | stat_card | markdown | heatmap | activity_feed | pivot_table | pie_chart

Widget visualization type

request.json 
{
  "data": {
    "attributes": {
      "config": "<config>",
      "data_model_id": "00000000-0000-4000-8000-000000000001",
      "embed_filter_allowlist": "<embed_filter_allowlist>",
      "filters": "<filters>",
      "name": "Example",
      "organization_id": "00000000-0000-4000-8000-000000000001",
      "source": "<source>",
      "type": "<type>"
    },
    "type": "resource"
  }
}

Success response

201 Success
Media type
application/vnd.api+json
Schema
object

Errors and retries

Keep x-request-id from failed responses. Retry only rows marked retryable, and obey Retry-After when present.

Status Code Recovery Meaning
401 unauthorized Do not retry unchanged A valid bearer token is required.
403 forbidden Do not retry unchanged The service account lacks the required scope or object access.
429 rate_limited Retry after guidance The request exceeded its rate window; wait for Retry-After.
409 idempotency_key_reused Do not retry unchanged The key was previously used for a different request.
422 invalid_request Do not retry unchanged The request document failed resource validation.

Related guides

JSON:API documents and media types Read and write Hodoflow's path-versioned JSON:API documents with the correct envelopes, headers, resource identities, and relationships. Perform an idempotent write Create one test dashboard through JSON:API, replay the identical request safely, and recognize a conflicting key reuse.