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.

Interactive API Reference

The full endpoint reference — including artifact search and fetch — lives in the REST API reference, generated from the live OpenAPI spec with an interactive playground for every endpoint.

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 single workspace within an organization. A key can push draft artifacts into its workspace and read that workspace's validated artifacts (via the REST API and the MCP server) — treat a leaked key as exposing the workspace's validated intelligence, not just draft-write access. Generate keys in Settings > API Keys from the workspace you want to integrate with.

Base URL

https://poc.assemble.site.avrdevelopment.com

Endpoints

Push Artifact

Create a new artifact in the workspace.

POST /api/v1/artifacts

Validated artifacts can also be read back over HTTPS — GET /api/v1/artifacts?query=… (semantic search) and GET /api/v1/artifacts/{id} (detail). See the REST API reference for those.

Looking for read-only access from MCP clients? See Artifact MCP Server for workspace-scoped artifact search and fetch tools.

Headers

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

Request Body

{
  "summary": "Q3 revenue increased 12% quarter-over-quarter",
  "content": {
    "root": "doc",
    "elements": {
      "doc": {
        "type": "Section",
        "props": {},
        "children": ["overview", "metrics", "drivers", "chart", "findings", "recommendation"]
      },
      "overview": {
        "type": "Markdown",
        "props": { "content": "## Overview\n\nRevenue grew from **$1.07M** to **$1.2M** in Q3, driven by new enterprise deals." }
      },
      "metrics": {
        "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" }
          ]
        }
      },
      "drivers": {
        "type": "Markdown",
        "props": { "content": "## Key Drivers\n\nEnterprise segment grew 34% while mid-market held steady..." }
      },
      "chart": {
        "type": "ChartImage",
        "props": { "src": "https://your-storage.com/chart.png", "caption": "Enterprise deals drove the Q3 jump" }
      },
      "findings": {
        "type": "Markdown",
        "props": { "content": "## 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" }
      },
      "recommendation": {
        "type": "Callout",
        "props": { "type": "recommendation", "text": "Increase enterprise sales headcount by 2 reps for Q4 to capture momentum." }
      }
    }
  },
  "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
`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
`content`	object	Document content (see Content Format) — an element tree of markdown and rich blocks. Omit it for a summary-only artifact.
`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?}`)
`codeExecuted`	array	Code that produced the insight (`{language, code, output?}`)
`trigger`	string	Optional and ignored — API pushes are always recorded as `"external"`

Content Format

Artifact content is an element tree: a flat map of elements plus the key of the root element. The root should be a Section whose children list the document's elements in order. Markdown prose is itself a block (Markdown), so a document interleaves prose with rich blocks by ordering children.

{
  "root": string,        // Key of the root element (use a Section)
  "elements": {          // Flat map of element key → element
    "<key>": {
      "type": string,    // Block type (see below)
      "props": object,   // Block-specific properties
      "children": string[]  // Section only — child element keys in document order
    }
  }
}

Available block types:

Type	Props	Description
`Section`	`{}` (+ `children`)	Layout container — use as the document root
`Markdown`	`{content}`	Markdown prose — headings, text, lists, inline emphasis
`MetricRow`	`items: [{label, value, change?, direction?}]`	Row of 3–4 headline metrics with optional change indicators
`ChartImage`	`{src, caption?}`	Chart or image with a takeaway caption
`Callout`	`{type: "recommendation"\|"warning"\|"info", text}`	Highlighted callout for the single most important action or caveat
`DataTable`	`{columns, rows, caption?}`	Small evidence table (aim for ≤10 rows) supporting a specific claim
`DataSourceList`	`{sources: [{name, type}]}`	Badge list of data sources behind the analysis
`SqlEvidence`	`{connectionName, sql, rowCount?, connectorType?}`	The exact SQL behind a database-backed finding

Direction values for MetricRow: "up" (green), "down" (red), "neutral" (gray). DataSourceList and SqlEvidence are provenance blocks — the renderer pulls them out of the body into a collapsible evidence appendix.

Content is stored as submitted and is not schema-validated at push time. Content that doesn't match this shape won't render as a document body — the artifact falls back to its summary, findings, and recommendations. Stick to the structure above so the full document renders.

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://poc.assemble.site.avrdevelopment.com/api/v1/artifacts \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Weekly churn rate: 2.3%",
    "content": {
      "root": "doc",
      "elements": {
        "doc": { "type": "Section", "props": {}, "children": ["body"] },
        "body": {
          "type": "Markdown",
          "props": { "content": "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

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