GraphQL API

Query and mutate dashboards, widgets, data sources, and integrations via GraphQL.

The widgets.pro API is GraphQL-only. Every action available in the UI is available through the API.

Endpoint

https://api.widgets.pro/graphql

Authentication

All requests require a Bearer token. Generate one in Settings → API keys in the web app.

curl -X POST https://api.widgets.pro/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id name email } }"}'

API keys can be scoped to a single organization and revoked at any time. Don't commit them to source control — use environment variables or a secrets manager.

Schema explorer

Open https://api.widgets.pro/graphql in a browser to use the Apollo Sandbox explorer (auth via Authorization header). Or download the schema for tools like GraphQL Code Generator.

Common queries

List dashboards

query {
  dashboards {
    id
    title
    description
    createdAt
    widgetCount
  }
}

query GetWidget($id: ID!) {
  widget(id: $id) {
    id
    type
    title
    blueprint {
      meta { title }
      root { type props }
    }
  }
}

Common mutations

Create a dashboard

mutation {
  createDashboard(input: {
    title: "Sales Overview"
    description: "Monthly sales metrics"
  }) {
    id
    title
  }
}

mutation {
  addWidget(input: {
    dashboardId: "dsh_abc123"
    definitionSlug: "chart"
    position: { x: 0, y: 0, w: 6, h: 4 }
  }) {
    id
  }
}

Subscriptions

Real-time updates over WebSocket:

subscription {
  widgetUpdated(dashboardId: "dsh_abc123") {
    id
    blueprint
  }
}

Rate limits

Plan	Requests / minute
Free	60
Pro	300
Business	1000

The API returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response. Exceeded limits return 429 Too Many Requests.

Errors

GraphQL errors follow the standard format:

{
  "errors": [
    {
      "message": "Dashboard not found",
      "extensions": {
        "code": "NOT_FOUND",
        "requestId": "req_abc123"
      }
    }
  ]
}

Common codes: UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_SERVER_ERROR. Always log the requestId — it lets support trace your call.