Capability Map

Choose an artifact app when the deliverable is a hosted dashboard, website, private tool, or interactive app with a versioned artifact-app.json manifest. The current runtime target is aws_lambda_function_url; supported languages are Node and Python.

Need	Artifact-native path	Do not infer
Page, asset, or private app API	Declare a route. API routes live under /_artifact/*; use relative browser fetches such as ./_artifact/data/summary.	Global /api/* access or root-absolute /_artifact/* fetches.
Read-only reporting or derived metrics	Declare bounded live SQL in datasets[], with a matching /_artifact/data/<name> API route.	A database URL or direct database connection in runtime/browser code.
Narrow source count	Use a live sourceBinding with access: "service_aggregate" and aggregate.type: "count".	Sum, average, joins, ratios, or custom aggregates through this binding.
Per-viewer customer rows	Use the viewer source-binding path. It requires a session and is currently limited to resource: "customers", emailField: "email".	General row-level authorization for arbitrary sources.
Third-party API	Use a declared Secrets Manager ARN and a server-side artifact route.	Browser credentials, ordinary env-var secrets, or direct vendor calls from the browser.
Simple LLM turn	Private server-side /_artifact/api/* route plus one bounded Bedrock Converse call.	Agent loops, tools, memory, streaming, history, or a caller-supplied model/API key.
Published customer documents	For a normal app, declare an exact knowledgeBases[] binding and read it through relative ./_artifact/knowledge/<alias> list, search, and fetch routes.	Company Knowledge, a source binding, direct /knowledge/* delivery, a Knowledge Base bearer, provider/storage identifiers, draft content, or Knowledge Bases in a hosted MCP artifact.
MCP tools for Topline chat or Topline Coding Agent tasks	kind: "mcp_server" from fastmcp-server, with the one canonical /_artifact/mcp route.	A credential in artifact source, direct self-connection, self-approval, or bypass of Developer Access tool review.
Large or expensive report	A precomputed dataset backed by private tenant-scoped object storage and an enabled refresh_live_cache schedule.	Direct object URLs or a slow fallback query before the first successful warm.
New customer API ingestion	Data Sources build using the shared REST connector when it fits, otherwise a custom platform connector. With the Data Sources workspace on, the source becomes a data pipeline artifact when scheduled.	An artifact app that owns a credential, checkpoint, scheduler, or ETL loop.
Which tables sync and when	The source's data pipeline artifact: edit its pipelineManifest as a draft (save_pipeline_artifact_draft); a person publishes.	Changing scheduler jobs directly, or publishing, pausing or resuming from a coding task.

Artifact-native versus adjacent work

Artifact apps own their package, manifest, declared routes, UI, bounded read-only datasets, runtime API code, and manifest-declared refresh contract. They can use platform-provided viewer/session, data-query, secret-reference, object-storage, and Bedrock capabilities only through those declarations.

Artifact-adjacent work is required when the source is not already available to the approved read-only tools: connector onboarding, source synchronization, catalog exposure, and upstream data quality/freshness. Stop with a data blocker instead of adding a credential, unbounded query, or unsupported network path to the app.

For a new customer API, this adjacent work is itself a first-class Data Sources workflow: source and connection intake, secret-reference capture, table approval, bounded sample sync, connector-owned materialization, catalog registration, and a normal scheduled pipeline. With the Data Sources workspace on, that source is represented by one data pipeline artifact whose pipelineManifest names its tables and schedules; the platform objects above stay the system of record for credentials, checkpoints, rows and runs. Any other saved artifact may hold the human-readable build brief, but it cannot substitute for those durable objects.

Platform-service work is outside the app package: IAM, Lambda/runtime provisioning, database/source credentials, secret creation, raw scheduler jobs, object-storage URLs, direct cloud deploys, and live promotion. An app can declare what it needs; it does not grant itself those platform capabilities.

App shape

Pick the manifest kind that matches the result: dashboard, mini_page, briefing, table, tool, or the app-only mcp_server. Every v2 manifest declares its runtime, build, validation commands, routes, source bindings (possibly empty), environment names, and viewerPolicy (private or tenant). Datasets and refresh schedules are optional only when the app does not need them.

Use the manifest as the boundary: each dataset name contains only letters, numbers, underscores, or hyphens and maps exactly to /_artifact/data/<name>; each route is declared once. Set maximum rows, bytes, timeout, and rate/cache settings appropriate to the displayed result rather than treating the app as a general query client.

mcp_server is the deliberate exception to the ordinary artifact data shape: its sourceBindings, datasets, and refreshSchedules must be empty. Its machine credential authorizes only the exact live MCP route, not a callback to artifact data routes. Use approved secretBindings for server-side external APIs or move Topline-owned data and recurring work behind a reviewed platform service.