Assemble API

The Assemble API allows external agents, tools, and services to push artifacts (insights, analyses, predictions) into your workspace. All artifacts — whether generated internally via chat or pushed externally — are first-class citizens: browsable, referenceable, and feedbackable.

Authentication

All API requests require an API key, which you can generate in your workspace Settings.

Authorization: Bearer your-api-key

API keys are scoped to a workspace. Generate them in Settings > API Keys.

Base URL

https://decisive-bobcat-593.convex.site

Endpoints

Push Artifact

Create a new artifact in the workspace.

POST /api/v1/artifacts

Headers

Header	Value
`Authorization`	`Bearer <api-key>`
`Content-Type`	`application/json`

Request Body

{
  "summary": "Q3 revenue increased 12% quarter-over-quarter",
  "content": {
    "markdown": "## Overview\n\nRevenue grew from **$1.07M** to **$1.2M** in Q3, driven by new enterprise deals.\n\n{{block:metrics-1}}\n\n## Key Drivers\n\nEnterprise segment grew 34% while mid-market held steady...\n\n{{block:chart-1}}\n\n## Key Findings\n\n- Enterprise deals accounted for 78% of growth\n- Average deal size increased from $45K to $62K\n- Sales cycle shortened by 8 days\n\n## Recommendations\n\n{{block:callout-1}}\n\n{{block:callout-2}}",
    "blocks": [
      {
        "id": "metrics-1",
        "type": "MetricRow",
        "props": {
          "items": [
            { "label": "Revenue", "value": "$1.2M", "change": "+12%", "direction": "up" },
            { "label": "Deals Closed", "value": "47", "change": "+8", "direction": "up" },
            { "label": "Avg Deal Size", "value": "$62K", "change": "+38%", "direction": "up" }
          ]
        }
      },
      {
        "id": "chart-1",
        "type": "ChartImage",
        "props": { "src": "https://your-storage.com/chart.png", "caption": "Revenue by quarter" }
      },
      {
        "id": "callout-1",
        "type": "Callout",
        "props": { "type": "recommendation", "text": "Increase enterprise sales headcount by 2 reps for Q4 to capture momentum." }
      },
      {
        "id": "callout-2",
        "type": "Callout",
        "props": { "type": "warning", "text": "Mid-market pipeline is flat — investigate whether pricing change affected inbound." }
      }
    ]
  },
  "why": "Revenue growth accelerated due to new enterprise deals",
  "confidence": 0.85,
  "confidenceExplanation": "Based on complete CRM data for Q3",
  "keyFindings": [
    "Enterprise deals accounted for 78% of growth",
    "Average deal size increased from $45K to $62K",
    "Sales cycle shortened by 8 days"
  ],
  "recommendations": [
    { "text": "Increase enterprise sales headcount by 2 reps for Q4", "type": "recommendation" },
    { "text": "Mid-market pipeline is flat — investigate pricing impact", "type": "warning" }
  ],
  "trigger": "external",
  "sourceSystem": "revenue-tracker",
  "dataSources": [
    { "type": "external", "name": "CRM Export Q3", "id": "crm-q3-2024" }
  ]
}

Required Fields

Field	Type	Description
`summary`	string	One-line headline of the insight (max 100 chars)
`content`	object	Document content (see Content Format)
`why`	string	Why this insight matters
`confidence`	number	Confidence score 0.0–1.0
`confidenceExplanation`	string	Reasoning for the confidence level

Optional Fields

Field	Type	Description
`recommendation`	string	Legacy single recommendation (prefer `recommendations` array)
`keyFindings`	string[]	Structured key findings — machine-readable
`recommendations`	array	Structured recommendations with type (see below)
`sourceSystem`	string	Name of the external system
`dataSources`	array	Data sources used (`{type, name, id?}`)
`citations`	array	Specific evidence citations
`codeExecuted`	array	Code that produced the insight (`{language, code, output?}`)
`trigger`	string	Always `"external"` for API pushes

Content Format

Artifact content is a markdown document with optional rich blocks for elements markdown can't express.

{
  "markdown": string,    // Markdown body — headings, text, tables, lists, code blocks
  "blocks": [            // Optional rich blocks referenced via {{block:id}} in markdown
    {
      "id": string,      // Referenced in markdown as {{block:id}}
      "type": string,    // Block type (see below)
      "props": object    // Block-specific properties
    }
  ]
}

Available block types:

Type	Props	Description
`MetricRow`	`items: [{label, value, change?, direction?}]`	Row of key metrics with optional change indicators
`ChartImage`	`{src, caption?}`	Chart or image with optional caption
`Callout`	`{type: "recommendation"\|"warning"\|"info", text}`	Highlighted callout box
`DataSourceList`	`{sources: [{type, name}]}`	List of referenced data sources

Direction values for MetricRow: "up" (green), "down" (red), "neutral" (gray).

Recommendations Array

{
  "recommendations": [
    { "text": "What to do", "type": "recommendation" },
    { "text": "Something to watch out for", "type": "warning" },
    { "text": "Additional context", "type": "info" }
  ]
}

These are stored as structured data and are machine-readable — other systems can consume them via the API without parsing markdown.

Response

{
  "artifactId": "abc123",
  "status": "draft"
}

Example: Simple Artifact

curl -X POST https://decisive-bobcat-593.convex.site/api/v1/artifacts \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Weekly churn rate: 2.3%",
    "content": {
      "markdown": "Churn increased from 1.8% to 2.3% this week, correlating with the pricing change on Monday.\n\n## Key Findings\n\n- Churn spike began 48 hours after pricing update\n- 73% of churned accounts were on the Basic plan\n- Enterprise retention unchanged"
    },
    "why": "Churn spike correlates with pricing change",
    "confidence": 0.9,
    "confidenceExplanation": "Complete subscription data",
    "keyFindings": [
      "Churn spike began 48 hours after pricing update",
      "73% of churned accounts were on the Basic plan",
      "Enterprise retention unchanged"
    ],
    "recommendations": [
      { "text": "Consider grandfathering existing Basic plan users", "type": "recommendation" },
      { "text": "Monitor enterprise churn weekly for delayed impact", "type": "warning" }
    ]
  }'

Artifact Lifecycle

Pushed artifacts start with status draft. Team members can:

Validate — confirm the insight is accurate
Dispute — flag as incorrect with a reason
Supersede — mark as replaced by a newer artifact

The agent can reference external artifacts in conversations, just like internally-generated ones. Artifacts are also retained to the workspace memory bank, so the agent recalls them in future analyses.

API Key Management

Generate and manage API keys in your workspace Settings page. Each key is scoped to one workspace.

Keys are shown once on creation — store them securely
Revoke keys anytime from Settings
Each key has a name for identification

Assemble API

On this page