> ## Documentation Index
> Fetch the complete documentation index at: https://widgetic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

> [!NOTE]
>
> If you're a **partner** looking to embed the canvas in your platform, see the [Partner Documentation](https://widgetic.com/docs/partners/overview.md) 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

> [card] [Widgets](https://widgetic.com/docs/api/widgets.md)
>
> Create and manage individual widgets

> [card] [Compositions](https://widgetic.com/docs/api/compositions.md)
>
> Combine widgets into layouts

> [card] [Canvases](https://widgetic.com/docs/api/canvases.md)
>
> Work with widget editing canvases

## Quick Example

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

```bash cURL theme={null}
curl -X GET "https://api.widgetic.com/v1/widgets" \
  -H "Authorization: Bearer wgt_usr_your_api_key"
```

```typescript TypeScript SDK theme={null}
import { WidgetsApi } from '@widgetic/api-sdk-ts';

const widgets = new WidgetsApi('wgt_usr_your_api_key');

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

console.log(`Found ${meta.total} widgets`);
data.forEach(widget => {
  console.log(`- ${widget.name} (${widget.id})`);
});
```

## API Response Format

All API responses follow a consistent format:

### Success Response

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

### Error Response

```json theme={null}
{
  "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:

```typescript theme={null}
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](https://widgetic.com/docs/reference/rate-limits.md) 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:

```bash theme={null}
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](https://widgetic.com/docs/reference/idempotency.md) for more details.

## Using the SDK

We recommend using the TypeScript SDK for the best experience:

```bash theme={null}
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

```typescript theme={null}
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](https://widgetic.com/docs/api/widgets.md)

**2. Build Compositions**

Combine widgets into [compositions](https://widgetic.com/docs/api/compositions.md)

**3. Check API Reference**

Browse the complete [API Reference](https://widgetic.com/api-reference/introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.