Ownership & Distribution¶

Understanding how toolkit ownership works is essential for partners planning their distribution strategy. This guide explains the ownership model, the distinction between provenance and governance, and how to leverage both API-based and file-based distribution channels.

Ownership Types¶

Toolkit ownership has two dimensions: provenance (who authored it) and governance (who controls the installed copy).

Provenance (Manifest Header)¶

The ownership_type field in a manifest declares who authored/distributed the toolkit:

Governance (Installed Toolkit)¶

When a toolkit is installed, its governance determines who can modify or delete it:

The Governance Principle¶

The installed ownership_type answers: "Who controls this toolkit?"

• SYSTEM toolkits are read-only for everyone except Contio staff
• PARTNER toolkits can only be modified through the Partner Admin API using your API key
• WORKSPACE toolkits can be modified by workspace administrators

Provenance vs. Governance¶

A common point of confusion is the difference between the ownership_type field in a manifest file and the ownership_type of an installed toolkit. These serve different purposes:

Why This Distinction Matters¶

When a manifest is imported via the file import endpoint (POST /api/toolkits/import), the manifest provenance is not transferred to governance. Instead:

1. The manifest header declares provenance (e.g., "PARTNER" or "PUBLIC")
2. The import endpoint creates a WORKSPACE-governed toolkit
3. The workspace admin now owns and can customize the imported copy

This separation enables powerful distribution patterns where authors can share their toolkits externally while customers retain full control over their imported copies.

Examples of Provenance vs. Governance¶

Two Distribution Channels¶

Partners have two complementary ways to distribute toolkits:

Channel 1: Partner Admin API (Direct Installation)¶

The standard approach for integrated partner applications:

Partner App ──▶ POST /v1/partner/admin/toolkits ──▶ PARTNER-owned toolkit
                         │
                         ▼
              POST /v1/partner/user/toolkits/{id}/install
                         │
                         ▼
              Workspace receives PARTNER toolkit (partner controls)

Characteristics: - Toolkit remains PARTNER-owned after installation - Only your application can modify the toolkit content - Upgrades are pushed automatically when you update the toolkit - Best for: SaaS integrations, managed deployments, premium features

Channel 2: External File Distribution (Marketplace Model)¶

Export your toolkit as a standalone JSON file for external distribution:

Partner App ──▶ GET /v1/partner/admin/toolkits/{id}/export ──▶ JSON file
                                                                   │
                         ┌─────────────────────────────────────────┘
                         ▼
              Customer downloads from marketplace / website / purchase
                         │
                         ▼
              POST /api/toolkits/import (workspace admin)
                         │
                         ▼
              Workspace receives WORKSPACE-owned toolkit (customer controls)

Characteristics: - Exported file includes full manifest with provenance header ("ownership_type": "PARTNER", "PUBLIC", etc.) - When customer imports, they receive a WORKSPACE-governed copy - Customer can customize, extend, or modify the imported toolkit - Your original PARTNER toolkit (if any) remains unchanged - Best for: Marketplace sales, downloadable templates, one-time purchases

Distribution Strategy Examples¶

Example 1: Freemium Model¶

Offer a free toolkit via file download, premium features via API:

┌──────────────────────────────────────────────────────────────-───┐
│                     Partner Distribution                         │
├────────────────────────────────────────────────────────────-─────┤
│                                                                  │
│  FREE TIER (File Distribution)                                   │
│  ─────────────────────────────                                   │
│  • Export "essentials" toolkit as JSON                           │
│  • Host on website / GitHub / marketplace                        │
│  • Customer imports → WORKSPACE-owned                            │
│  • Customer can customize freely                                 │
│                                                                  │
│  PREMIUM TIER (API Distribution)                                 │
│  ──────────────────────────────                                  │
│  • Full toolkit installed via Partner API                        │
│  • Remains PARTNER-owned                                         │
│  • Automatic updates when you publish new versions               │
│  • Premium features only available through your app              │
│                                                                  │
└─────────────────────────────────────────────────────────-────────┘

Example 2: Marketplace with Customization¶

Sell toolkits on a marketplace where customers can modify after purchase:

1. Create the toolkit via Partner Admin API
2. Export the manifest to a JSON file
3. List on marketplace (your website, partner portal, etc.)
4. Customer purchases and downloads the JSON file
5. Customer imports via their workspace admin panel
6. Customer owns the copy and can customize for their organization

This model works well for: - Industry-specific meeting templates - Compliance-focused workflows - Vertical solutions (legal, healthcare, finance)

Example 3: Hybrid Managed + Self-Service¶

Some customers want managed updates; others want full control:

Slug Collision Protection¶

Slugs are unique identifiers for toolkits within a scope. Contio enforces protection rules to prevent accidental overwrites:

Protection Rules¶

Why This Matters¶

If you've installed your toolkit via the Partner Admin API (creating a PARTNER-owned toolkit), your customers cannot accidentally overwrite it by importing a file with the same slug. This protects your managed installations from being replaced.

Scenario: You install "acme-sales-toolkit" via API. Later, someone shares an old exported version of the same toolkit. If a workspace admin tries to import it:

POST /api/toolkits/import
{
  "name": "Acme Sales Toolkit",
  "slug": "acme-sales-toolkit",  // Same slug as existing PARTNER toolkit
  ...
}

Response: 403 Forbidden
"cannot import over PARTNER toolkit \"acme-sales-toolkit\""

Recommended Slug Naming¶

To avoid conflicts and clearly identify your toolkits:

{partner-prefix}-{toolkit-name}[-{variant}]

Examples:
  acme-sales-discovery
  acme-sales-discovery-lite     (free version)
  acme-sales-discovery-pro      (premium version)
  acme-sales-discovery-custom   (customer-modified version)

Exporting Toolkits for Distribution¶

Single Toolkit Export¶

GET /v1/partner/admin/toolkits/{toolkitId}/export
Authorization: X-API-Key your-api-key

Response:

{
  "name": "Acme Sales Discovery",
  "slug": "acme-sales-discovery",
  "version": "2.1.0",
  "ownership_type": "PARTNER",
  "manifest": {
    "schema_version": "1",
    "toolkit_prompt": "You are a sales discovery assistant...",
    "templates": [...],
    "next_steps": [...],
    "action_buttons": [...],
    "shortcuts": []
  }
}

Bulk Export¶

Export multiple toolkits in a single request:

POST /v1/partner/admin/toolkits/export
Authorization: X-API-Key your-api-key
Content-Type: application/json

{
  "toolkit_ids": ["tk_abc123", "tk_def456"]
}

What's Included in Exports¶

Customer Import Experience¶

When a workspace admin imports your exported toolkit, they use the internal import endpoint:

POST /api/toolkits/import
Authorization: Bearer {workspace-admin-token}
Content-Type: application/json

{
  "name": "Acme Sales Discovery",
  "slug": "acme-sales-discovery-imported",  // Often modified to avoid conflicts
  "version": "2.1.0",
  "ownership_type": "PARTNER",              // Preserved from your export
  "manifest": {
    "schema_version": "1",
    ...
  }
}

What happens:

1. The import endpoint validates the manifest structure
2. All entities are created with ownership_type = WORKSPACE
3. The toolkit itself is created with ownership_type = WORKSPACE
4. The customer now fully owns and controls the imported copy
5. Your original PARTNER toolkit (if it exists) is unaffected

Version Management Across Channels¶

API-Distributed Toolkits (PARTNER-owned)¶

When you update a PARTNER toolkit, installed workspaces can receive updates:

// Update your toolkit
await sdk.admin.updateToolkit(toolkitId, {
  version: '2.2.0',
  manifest: updatedManifest
});

// Workspaces with the toolkit installed can pull updates
// (implementation depends on your upgrade strategy)

File-Distributed Toolkits (WORKSPACE-owned)¶

Customers who imported via file do not receive automatic updates. To update them:

1. Publish a new version on your distribution channel
2. Notify customers of the update
3. Customer re-imports (may need to use a new slug or delete old version first)

Consider including version information in your distribution:

acme-sales-discovery-v2.1.0.json
acme-sales-discovery-v2.2.0.json

Best Practices¶

For API Distribution¶

• ✅ Use consistent slugs across all customer installations
• ✅ Version your toolkits semantically (major.minor.patch)
• ✅ Document breaking changes between versions
• ✅ Provide upgrade paths for customers on older versions

For File Distribution¶

• ✅ Include version in filename: toolkit-name-v1.2.0.json
• ✅ Provide a changelog alongside your toolkit files
• ✅ Consider offering both "stable" and "latest" downloads
• ✅ Document any manual steps required after import
• ✅ Use distinct slugs for free vs. premium variants

For Hybrid Distribution¶

• ✅ Use slug suffixes to distinguish variants: -lite, -pro, -custom
• ✅ Clearly communicate which version a customer has
• ✅ Provide migration paths from file-distributed to API-managed

Licensing¶

When distributing toolkits externally, it's important to declare the terms under which recipients can use the content. The license field in the manifest header provides a machine-readable declaration of usage rights.

SPDX License Identifiers¶

Contio uses SPDX license identifiers — the industry standard for machine-readable license declarations. These are the same identifiers used by npm, GitHub, and other major package ecosystems.

Manifest License Fields¶

Two fields are available in the manifest header:

{
  "name": "Acme Sales Discovery",
  "slug": "acme-sales-discovery",
  "version": "2.1.0",
  "ownership_type": "PARTNER",
  "license": "LicenseRef-AcmePartner",
  "license_url": "https://acme.com/toolkit-license",
  "manifest": {
    "schema_version": "1",
    ...
  }
}

Choosing a License¶

For Free/Open Toolkits:

For Commercial/Proprietary Toolkits:

Use LicenseRef-{YourCompany} with a license_url pointing to your terms:

{
  "license": "LicenseRef-AcmePartner",
  "license_url": "https://acme.com/partner-toolkit-terms"
}

For All-Rights-Reserved Content:

{
  "license": "UNLICENSED"
}

License in Exports¶

When you export a toolkit, the license fields are included in both the metadata and the manifest:

{
  "metadata": {
    "name": "Acme Sales Discovery",
    "slug": "acme-sales-discovery",
    "version": "2.1.0",
    "license": "LicenseRef-AcmePartner",
    "license_url": "https://acme.com/toolkit-license"
  },
  "manifest": {
    "schema_version": "1",
    "license": "LicenseRef-AcmePartner",
    "license_url": "https://acme.com/toolkit-license",
    ...
  }
}

This ensures the license declaration travels with the toolkit through both API responses and file-based distribution.

Licensing Best Practices¶

For API Distribution (PARTNER-owned):

• ✅ License is informational — your app controls access
• ✅ Consider UNLICENSED or a custom LicenseRef-* for SaaS-delivered content
• ✅ Terms are typically covered by your partner agreement

For File Distribution (Marketplace):

• ✅ Always include a license — customers need to know their rights
• ✅ Use license_url to link to full terms
• ✅ Consider CC-BY-4.0 for freely-shareable templates
• ✅ Use LicenseRef-* with clear terms for commercial products

For Hybrid Distribution:

What License Protects¶

The license field declares terms for the intellectual property in your toolkit:

• ✅ AI prompts and persona instructions
• ✅ Meeting template structures and guidance
• ✅ Workflow configurations
• ✅ Action button logic and messaging

It does not grant or restrict:

• ❌ API access (controlled by authentication)
• ❌ Installation rights (controlled by ownership_type)
• ❌ Modification rights (controlled by governance, not license)

Example: Marketplace Distribution with License¶

{
  "name": "Legal Discovery Toolkit",
  "slug": "acme-legal-discovery",
  "version": "1.0.0",
  "ownership_type": "PARTNER",
  "license": "LicenseRef-AcmeLegal",
  "license_url": "https://acme.com/legal-toolkit-license",
  "manifest": {
    "schema_version": "1",
    "license": "LicenseRef-AcmeLegal",
    "license_url": "https://acme.com/legal-toolkit-license",
    "toolkit_prompt": "You are a legal discovery assistant...",
    "templates": [...]
  }
}

When a customer imports this toolkit: 1. They receive a WORKSPACE-owned copy (can customize) 2. The license declaration is preserved (usage terms still apply) 3. Attribution requirements (if any) remain in effect

Export Controls¶

Export functionality is governed by provenance to protect platform IP and contractual partner content. The rules are based on the toolkit's ownership_type:

Export Eligibility by Provenance¶

Why Restrict SYSTEM and PARTNER Exports?¶

SYSTEM toolkits are Contio's intellectual property:

• Built-in templates, AI prompts, and workflows developed by Contio
• Distributed exclusively through the platform
• Export would allow unauthorized redistribution

PARTNER toolkits are protected content:

• Partners have formal agreements with Contio
• Content may be licensed exclusively for in-platform use
• Export restrictions honor contractual terms between Contio and partners

Allowed Exports¶

PUBLIC toolkits can be exported because:

• Authors intend for open distribution (marketplaces, GitHub, etc.)
• No contractual restrictions on redistribution
• The PUBLIC provenance signals community/open availability

WORKSPACE-assembled toolkits can be exported because:

• Users created or customized the content themselves
• They have full ownership and control
• Exporting their own work is a natural expectation

Export Behavior in the API¶

When a toolkit is not exportable, the export endpoints return a 403 Forbidden response:

GET /v1/partner/admin/toolkits/{toolkitId}/export

{
  "error": "cannot export SYSTEM toolkit",
  "code": "export_restricted"
}

Practical Implications¶

Importing Exported Content¶

When a user imports an exported toolkit (a PUBLIC or WORKSPACE export), the imported copy becomes WORKSPACE-governed:

1. The imported toolkit is owned by the importing workspace
2. Workspace admins can modify, extend, or delete it
3. The original provenance (PUBLIC) is preserved in metadata for attribution

This ensures that: - Open-source attribution is maintained - Users retain full control over imported content - The original author's distribution intent is honored

Summary¶

See Also¶

• Manifest Format — Toolkit structure, schema versioning, and entity referencing
• Entity Lifecycle & Runtime Usage — Using the entity map and managing entities through versions
• Reference Patterns — $ref and $id cross-referencing
• Examples — Complete manifest examples including Robert's Rules toolkits