Quick Start

This quick start guide will get you up and running with Big Picture in minutes. We’ll create a product, publish a release, and configure a basic policy.

Prerequisites

• Big Picture instance (SaaS or self-hosted) with API access
• API credentials or OAuth token
• curl or similar HTTP client
• A software artifact (installer) ready to publish

Step 1: Authenticate

Obtain an API token or OAuth access token. The method depends on your deployment:

SaaS deployments:

# Use OAuth2 client credentials flow or service account token
export BP_API_TOKEN="your-token-here"

Self-hosted deployments:

# Use service account or API key as configured
export BP_API_TOKEN="your-token-here"
export BP_BASE_URL="https://your-big-picture-instance.com"

Step 2: Create a Product

Create your first product in the catalog:

curl -X POST "${BP_BASE_URL:-https://api.bigpicture.io}/v1/products" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Desktop App",
    "description": "My first Big Picture product"
  }'

Save the product_id from the response. You’ll need it for subsequent steps.

Step 3: Register an Artifact

Register your installer artifact. You can reference an external URL or upload to managed storage:

External artifact (recommended for quick start):

curl -X POST "${BP_BASE_URL:-https://api.bigpicture.io}/v1/artifacts" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "EXTERNAL",
    "sha256": "your-artifact-sha256-hash",
    "size_bytes": 12345678,
    "external_url": "https://your-artifact-repo.com/releases/v1.0.0/installer.msi"
  }'

Save the artifact_id from the response.

Note: For managed artifacts, see the Creating a Release guide for upload workflows.

Step 4: Create a Release

Publish a release on the stable channel:

curl -X POST "${BP_BASE_URL:-https://api.bigpicture.io}/v1/releases" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "your-product-id",
    "version": "1.0.0",
    "channel": "stable",
    "artifacts": [
      {
        "artifact_id": "your-artifact-id",
        "platform": "windows",
        "arch": "x86_64",
        "installer_type": "msi",
        "requires_admin": true
      }
    ]
  }'

The release is now published and available to clients.

Step 5: Query Update Decision

Test the update decision API as a client would:

curl -X POST "${BP_BASE_URL:-https://api.bigpicture.io}/v1/decision" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "product_id": "your-product-id",
        "current_version": "0.9.0",
        "channel": "stable",
        "tenant_id": "your-tenant-id"
      }
    ]
  }'

The response includes a signed decision indicating what action is allowed (NONE, NOTIFY, DOWNLOAD, or INSTALL).

Step 6: Configure Tenant Policy (Optional)

Set a policy for your tenant to control update behavior:

curl -X PUT "${BP_BASE_URL:-https://api.bigpicture.io}/v1/tenants/your-tenant-id/policies/your-product-id" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "stable",
    "mode": "NOTIFY_ONLY",
    "pinned_range": null
  }'

Policy modes:

• AUTO_INSTALL — Clients may install automatically
• NOTIFY_ONLY — Clients notify users but don’t install
• MANAGED_BY_IT — Clients defer to IT deployment tools

What’s Next?

You’ve successfully:

• Created a product
• Published a release
• Queried update decisions
• Configured tenant policy

Next steps:

• Learn about Creating a Release in detail
• Set up Licensing for access control
• Explore Workflows for operational procedures
• Review API Reference for complete API documentation

Troubleshooting

Authentication errors: Verify your API token and base URL are correct.

Product not found: Ensure you’re using the correct product_id from step 2.

Artifact verification failed: Verify the sha256 hash matches your artifact exactly.

Policy not applying: Check that tenant_id matches your authenticated tenant context.