# README

# 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](./quickstart.md) for a five-minute end-to-end example
- [Agents guide](./agents.md) for the four-tool architecture (data, context, assets, distribution)
- [API reference index](./api-reference/README.md) for every tool, scope, and data model
- [GitHub](https://github.com/amdahl/amdahl-app) for source code and issue tracking

## Table of contents

### Getting started

- [Quickstart](./quickstart.md)
- [Authentication](./authentication.md)
- [Sessions](./sessions.md)
- [Pagination and errors](./pagination-errors.md)
- [Versioning](./versioning.md)
- [Rate limits](./rate-limits.md)

### Using agents

- [Agents overview](./agents.md)
- [Recipe: draft a blog post](./recipes/draft-blog-post.md)
- [Recipe: run research](./recipes/run-research.md)
- [Recipe: react to a webhook](./recipes/react-to-webhook.md)

### Use cases

- [Metric (live numeric values)](../artifact-types-catalog.md#metric) - register a metric artifact whose `content_json` carries a query spec; read live values via `metrics.evaluate`.

### Guides

### Connections

- [Connecting data sources](./connections/connecting-data-sources.md) - 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)](./api-reference/connector-catalog.md) - every connector with its connect method, ownership, and data streams.

### Reference

- [Agent profiles](./reference/agent-profiles.md)
- [Layout hints](./reference/layout-hints.md) - per-type `layoutHints` config consumed by the frontend AutoRenderer.

### Webhooks

- [Webhooks guide](./webhooks.md)
- [Webhook events (auto-generated)](./api-reference/webhook-events.md)

### API reference

- [API reference index](./api-reference/README.md)
- [OpenAPI spec (JSON)](./api-reference/openapi.json)
- [Tools index (auto-generated)](./api-reference/tools/_index.md)
- [Scopes (auto-generated)](./api-reference/scopes.md)
- [Data models (auto-generated)](./api-reference/data-models.md)
- [Errors](./api-reference/errors.md)

### SDKs

- [curl](./sdk/curl.md)
- [TypeScript](./sdk/typescript.md)
- [Python](./sdk/python.md)

### Changelog

- [Changelog](./changelog.md)

## 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:

```json
{
  "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](./pagination-errors.md) 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`](../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`](../_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.