Partner Overview

Build widgets for your customers with the Widgetic API and show them in your platform

Partners build widgets for their own customers with the Widgetic API, and show them in their own platform with the embed code. In preview, you can also mount Widgetic’s own editors (a file browser, a composition editor, the AI widget creator and the screen where workflows are built) in your own page for one customer at a time, without your API key ever reaching the browser.

​

What Partners Can Do

Build and Embed Widgets

Create compositions with the API and show the published widgets in your platform with the embed code

Keep Track of End-Users

Keep a record of your customers as managed users

Editors in Your Page (preview)

Mount Widgetic’s File Browser, composition editor, AI widget creator and Workflows in your own page for one customer at a time

Credits & Billing

Pay by invoice, with tax, and track the AI credits on your account

Your Own Storage

Your customers’ files are kept in a bucket you own

Dashboard and Analytics

Your credits, invoices, customers and presets, and how their widgets are viewed

Notifications

Invoices, payments, low credits and pauses, by email and as signed webhooks

​

Partner API Key

Partners use API keys with the wgt_prt_ prefix. These keys have access to:

• All user-level endpoints
• Partner-specific endpoints (managed users, your contract, your invoices and your credits)

A key belongs to the account that administers your partner record. Only a person who is signed in on widgetic.com can make a key: a request made with an API key is refused, so a leaked key cannot be used to make a second one. A key can still list, rename, switch off and delete keys.

A key does everything its account may do, unless you limit it when you make it. A server that only reads your invoices, for example, can hold a key that cannot create anything. See Limit what a key can do.

​

Your Account Status

A partner account starts inactive and has no trial: you pay from the first day, and Widgetic activates the account once your contract is in force and your storage works. An invoice of your contract that is still unpaid after its due date stops the account by itself until it is paid, and Widgetic can also pause an account by hand. While the account is stopped, paused or not yet active, your customers cannot use your widgets or editors, and what you can change is limited to paying, buying credits, your storage, your notifications and your keys. See Account Status.

​

Architecture Overview

The dotted line is the short-lived token your server gives the page, so the editors work with one customer’s content and your API key stays on your server.

​

Key Concepts

​

Managed Users

A managed user is a record of one of your customers in your partner registry. It is not a login, and it does not own anything: everything you create through the API belongs to your administering account. What you can do is file a composition, a widget or an upload under a managed user when you create it, and list your account’s items by that managed user later, so each of your customers sees only their own. You create and manage managed users via the API.

curl -sS -X POST "https://api.widgetic.com/v1/managed-users" \
  -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "external_id": "your-platform-user-123", "metadata": { "name": "John Doe", "email": "[e-mail]" } }'

See Managed Users for the full picture.

​

Editor Sessions

An editor session is a short-lived token that your server makes for one managed user. Your page gives it to a Widgetic editor, which then reads and changes that customer’s content and nothing else. Your API key never reaches the browser. See Editor Sessions.

​

UI Components

Preview. The editors are new. They are built and tested, and you can try them now, but small details can still change while this label is on.

The UI SDK (@widgetic/ui-sdk) mounts four pieces in your own page. Each draws inside a shadow root, so your page’s styles and its own do not touch each other:

• File Browser: browse, upload and pick files, from Widgetic’s media library or from your own.
• Composition Editor: change the texts, pictures, colours and fonts of a widget, beside a live preview.
• Widget Creator: the whole Widgetic canvas, with the AI that builds a widget from a description.
• Workflows: chain a customer’s compositions into a path, with filters between them that decide which composition a visitor sees next.

See UI Components for the SDK and the File Browser, Canvas Embedding for the composition editor and the widget creator, and Workflows for the screen where a customer builds a path.

​

Preset Widgets

A preset is a widget of your own that you offer your customers as a starting point, under a short key your code uses. Your server lists them and gives a customer a copy (or a composition) of the one they pick. See Preset Widgets.

A workflow of yours can be a starting point too: your customers copy it, with a copy of every widget it chains, and build on it. See Starting points.

​

Credits System

You pay Widgetic by invoice, and Widgetic issues each invoice by itself: one for the credits of every billing period, at your price for a credit. Paying it adds those credits to your account, and when they run out you can buy extra credits with one API call. Credits pay for Widgetic’s AI: each generation uses 1 credit (the list price of a credit is $0.10). Creating compositions, embedding widgets, storage and API calls do not use credits. An invoice of your contract that is unpaid after its due date stops the account until it is paid. See Credits & Billing.

​

Getting Started

1. Make Your Partner API Key

   Contact our sales team to become a partner, and tell them the website where you will integrate Widgetic, such as acme.com. Widgetic sets up your partner account and records that website as your platform domain, so it and all of its subdomains can always show your widgets (see Security). The account stays inactive until it is activated (see below). You then sign in and make your own wgt_prt_ API key under Workspace settings → API keys. The secret is shown once, so store it when you make it. See Security for rotating and deleting keys.

2. Set Up Your Storage

   Save a bucket of your own on any S3-compatible service with PUT /partners/{partnerId}/storage. It is checked before it is saved, and every editor session and every upload with your key needs it. See Storage.

3. Agree Your Billing and Get Activated

   Read how credits and billing work, and agree the credits for each billing period, your price for a credit and the start date with Widgetic. Once your contract is in force and your storage works, Widgetic activates your account (see Account Status). There is no trial, so your first invoice is issued on the day your contract starts.

4. Keep Track of Your Customers

   Create managed users for your platform’s customers.

5. Build and Embed Widgets

   Create compositions with the API, publish them, and show them in your platform with the embed code.

6. Put the Editors in Your Page (optional)

   Make an editor session for the customer who is on the page, and mount a Widgetic editor with the UI SDK, so your customers make and change widgets without leaving your product.

7. Watch Your Account

   Open your dashboard for your credits, invoices, customers and analytics, and set an address for notifications so that your own system hears about invoices, low credits, pauses and stops.

​

Partner Endpoints

All partner endpoints require a wgt_prt_ API key. Key endpoints include:

Endpoint	Description
GET /managed-users	List your managed users
POST /managed-users	Create a managed user
POST /managed-users/{id}/editor-sessions	Make an editor session for one managed user
DELETE /managed-users/{id}/editor-sessions	End every editor session of a managed user
GET /partners/{id}/presets	List the widgets you offer as presets
PUT /partners/{id}/presets/{key}	Offer one of your widgets as a preset, or replace the preset with that key
POST /managed-users/{id}/presets/{key}/copy	Give a customer a copy of one of your presets
GET /partners/{id}/workflow-presets	List the workflows you offer as starting points
PUT /partners/{id}/workflow-presets/{key}	Offer one of your published workflows as a starting point, or replace the one with that key
POST /workspaces/personal/workflows/from-preset	Start a workflow for a customer (named in a header) from one of your starting points
GET /partners/mine	Find the partner you administer, its status and its platform domain
GET /partners/{id}/contract	Read your contract
PUT /partners/{id}/storage	Set the bucket your customers’ files are kept in
GET /partners/{id}/storage/usage	See what each of your customers keeps in storage
GET /partners/{id}/analytics/summary	See how your customers’ widgets are viewed and used
GET /partners/{id}/notifications	List what Widgetic told you
PUT /partners/{id}/notifications/settings	Choose where your notifications go, and set your webhook
GET /invoices/partner/{id}	List your invoices
GET /credits/user/{userId}/balance	Check your AI credit balance
POST /partners/{id}/credits/extra-invoice	Buy extra credits: an invoice that you pay on its page

See the API Reference for complete endpoint documentation. Filter by the Managed Users, Partners, Credits and Invoices tags.

​

Next Steps

Managed Users

Keep a record of your customers

Editor Sessions

Let a customer use Widgetic’s editors in your page

Credits & Billing

How you pay and how credits work

Account Status

Activation, pauses and what each one stops