API Overview

Use the Widgetic API to manage your widgets and compositions

The Widgetic API allows you to programmatically manage widgets, compositions, canvases, and more within your own account.

​

Who Is This For?

This section is for developers who:

• Want to integrate Widgetic widgets into their applications
• Need to manage widgets programmatically
• Are building tools that interact with their Widgetic account

If you’re a partner looking to embed the canvas in your platform, see the Partner Documentation instead.

​

API Key Types

Self-serve developers typically use:

Key Prefix	Description
wgt_usr_	Personal user API key
wdg_org_	Organization API key (shared access)

​

Core Resources

Widgets

Create and manage individual widgets

Compositions

Combine widgets into layouts

Canvases

Work with widget editing canvases

​

Quick Example

Here’s how to fetch your widgets using the API:

cURL

curl -X GET "https://api.widgetic.com/v1/widgets" \
  -H "Authorization: Bearer wgt_usr_your_api_key"

​

API Response Format

All API responses follow a consistent format:

​

Success Response

{
  "success": true,
  "data": { /* Resource or array of resources */ },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 150,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

​

Error Response

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Widget not found",
    "correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
  }
}

​

Pagination

List endpoints page their results with these parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
size	integer	20	Items per page (max 100)
sort	string	varies	Sort field and direction (e.g., created_at:desc), on the lists that take it

Each endpoint’s reference page says which of these it accepts. GET /widgets takes page and size but not sort (it is always newest first), and it returns the whole list when you pass neither, so always page it when you do not know how many widgets an account holds.

Example:

const { data, meta } = await widgets.getWidgets({
  page: 2,
  size: 50
});

if (meta?.hasNextPage) {
  // Fetch next page
}

​

Rate Limits

API requests are counted per API key over a 15-minute window, and the allowance depends on your plan. A partner key is held to a ceiling of 1,000,000 requests per 15 minutes, which is there to stop a runaway loop, not to meter a platform. Read the allowance that applies to you from the RateLimit-Limit header of any response.

A request over the limit is refused with 429 Too Many Requests and a Retry-After header.

See Rate Limits for more details.

​

Idempotency

For state-changing requests (POST, PATCH, and PUT on the endpoints that document it), provide an idempotency key so a retry never runs the operation twice. Some endpoints, such as POST /widgets, require it:

curl -X POST "https://api.widgetic.com/v1/widgets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{"name": "My Widget", "type": "chart", "content": {}}'

See Idempotency for more details.

​

Using the SDK

We recommend using the TypeScript SDK for the best experience:

npm install @widgetic/api-sdk-ts

The SDK provides:

• Type safety: Full TypeScript definitions
• Convenience: Automatic authentication handling
• Flexibility: Static tokens or async token providers

import { 
  WidgetsApi, 
  CompositionsApi, 
  CanvasesApi 
} from '@widgetic/api-sdk-ts';

// Initialize APIs
const widgets = new WidgetsApi('YOUR_API_KEY');
const compositions = new CompositionsApi('YOUR_API_KEY');
const canvases = new CanvasesApi('YOUR_API_KEY');

​

Next Steps

1. Explore Widgets

   Learn how to create and manage widgets

2. Build Compositions

   Combine widgets into compositions

3. Check API Reference

   Browse the complete API Reference