Quickstart

Create your first Vizco widget in minutes — from registration to delivery.

This guide walks you through creating and delivering your first Vizco widget end-to-end.

Prerequisites

  • A running Vizco backend instance
  • curl or any HTTP client
  • An Android, iOS, or React project (for SDK integration) or any HTTP client (for API delivery)

Steps

1

Register an account

Create your account and organization in a single request.

Register
curl -X POST https://your-api.com/api/auth/register \
-H "Content-Type: application/json" \
-d '{
  "organizationName": "My Company",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "password": "securepass123"
}'

Save the accessToken and organizationId from the response.

2

Create a project

Projects hold your assets, folders, widgets, and API keys.

Create project
curl -X POST https://your-api.com/api/organizations/{orgId}/projects \
-H "Authorization: Bearer {accessToken}" \
-H "Content-Type: application/json" \
-d '{
  "name": "My App",
  "slug": "my-app"
}'
3

Upload an asset

Upload an image to your project using multipart form data.

Upload asset
curl -X POST https://your-api.com/api/projects/{projectId}/assets \
-H "Authorization: Bearer {accessToken}" \
-F "file=@hero-banner.jpg"
4

Create a widget

Create a widget with your uploaded assets and desired layout. The assetIds array determines display order.

Create widget
curl -X POST https://your-api.com/api/projects/{projectId}/widgets \
-H "Authorization: Bearer {accessToken}" \
-H "Content-Type: application/json" \
-d '{
  "name": "Hero Carousel",
  "slug": "hero-carousel",
  "assetIds": ["{assetId}"],
  "layout": "CAROUSEL",
  "config": {
    "autoplay": true,
    "autoplaySpeed": 3000,
    "showDots": true
  }
}'
5

Create an API key

Generate a project-scoped API key for public widget delivery.

Create API key
curl -X POST https://your-api.com/api/projects/{projectId}/api-keys \
-H "Authorization: Bearer {accessToken}" \
-H "Content-Type: application/json" \
-d '{
  "name": "Android App Key",
  "permissions": "READ"
}'

Save your key

The full API key (e.g. pk_550e8400e29b41d4a716446655440000) is only returned once. Store it securely.

6

Publish the widget

Mark the widget as published so it's accessible via the public API.

Publish
curl -X PUT https://your-api.com/api/projects/{projectId}/widgets/{widgetId}/publish \
-H "Authorization: Bearer {accessToken}"
7

Fetch the widget publicly

Use the API key to fetch the published widget.

Fetch widget
curl https://your-api.com/api/v1/widgets/hero-carousel \
-H "X-API-Key: pk_550e8400e29b41d4a716446655440000"

The response includes the widget config and all associated asset URLs — ready to render.

What's next?

IntroductionAuthentication