Amdahl Consumer API Docs

This is the public-facing documentation for developers building on the Amdahl Platform API. It covers authentication, sessions, agents, webhooks, SDKs, and the full API reference. If you are integrating Amdahl into your own product or workflow, start here.

Quick links

• Quickstart for a five-minute end-to-end example
• Agents guide for the four-tool architecture (data, context, assets, distribution)
• API reference index for every tool, scope, and data model
• GitHub for source code and issue tracking

Table of contents

Getting started

• Quickstart
• Authentication
• Sessions
• Pagination and errors
• Versioning
• Rate limits

Using agents

• Agents overview
• Recipe: draft a blog post
• Recipe: run research
• Recipe: react to a webhook

Use cases

• Metric (live numeric values) - register a metric artifact whose content_json carries a query spec; read live values via metrics.evaluate.

Guides

Connections

• Connecting data sources - the four connect methods (OAuth redirect, API key, webhook, handle) and how to connect a source via the Connections page, the REST API, and MCP.
• Connector catalog (auto-generated) - every connector with its connect method, ownership, and data streams.

Reference

• Agent profiles
• Layout hints - per-type layoutHints config consumed by the frontend AutoRenderer.

Webhooks

• Webhooks guide
• Webhook events (auto-generated)

API reference

• API reference index
• OpenAPI spec (JSON)
• Tools index (auto-generated)
• Scopes (auto-generated)
• Data models (auto-generated)
• Errors

SDKs

• curl
• TypeScript
• Python

Changelog

• Changelog

Conventions

All consumer endpoints live under a single base URL:

https://api.amdahl.com/api/platform/v1

Every request must include a bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

Errors always follow a single envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "Human readable description",
    "details": { "field": "optional structured context" }
  }
}

The details field is optional. When present it is a JSON object that carries machine-readable context (field names, rate limit windows, offending IDs). See Pagination and errors for the full error code catalogue.

How to contribute

This consumer docs tree is the canonical reference going forward. The legacy single-file reference at docs/platform-api.md is kept for historical context only and will be removed once every section here reaches parity.

Several files under api-reference/ are generated from source and must not be edited by hand. The list is recorded in docs/_generated-marker.txt. CI enforces this: a pull request that edits a generated file without regenerating the whole set will fail the docs:verify check.

To regenerate:

npm run docs:generate:all

If you are adding new narrative docs (quickstart, recipes, SDK notes) edit the hand-written files directly. If you are adding a new tool, scope, or webhook event, update the backend source of truth and re-run the generator.