# README

# API Reference

This is the landing page for the full Amdahl Platform API reference. If you know what you are looking for, jump straight to the category below. If you are new, skim [How to use this reference](#how-to-use-this-reference) first.

## How to use this reference

The API is organized into **65 tools** grouped into 8 categories. Every tool is documented three ways:

1. **Tool pages** under [`tools/`](./tools/_index.md). One row per tool with HTTP method, path, required scopes, request schema, and response schema. Auto-generated from the backend source of truth; always accurate.
2. **OpenAPI spec**. Machine-readable schema for code generation and editor tooling: [`openapi.json`](./openapi.json) and [`openapi.yaml`](./openapi.yaml).
3. **Interactive Swagger UI** at `https://app.amdahl.co/api/platform/v1/docs`. Browse, search, and try requests from the browser.

For narrative guides that string tools together (auth, sessions, webhooks, recipes), go back to the [consumer docs index](../README.md).

## Browse by category

### Assets

The universal asset layer. Everything the platform generates (blog posts, battlecards, reports, calendars, analyses) is an artifact row with a typed `content_json` payload and a full version history.

- Tools index: [tools/\_index.md, filter Category = `assets`](./tools/_index.md)
- Key tools: `artifacts.create`, `artifacts.update`, `artifacts.list`, `artifacts.get_tree`, `artifacts.revert_to_version`

### Data

Low-latency read access to your interactions table, pre-computed clusters, and knowledge base.

- Tools index: [tools/\_index.md, filter Category = `data`](./tools/_index.md)
- Key tools: `data.explore`, `data.query`, `data.search`, `data.cluster_search`, `data.cluster_detail`
- Knowledge base: `knowledge_base.list`, `knowledge_base.search`, `knowledge_base.chat`, `knowledge_base.upload`

### Context

Business profile, session substrate operations, and the persisted context entry store (brand, audience, campaign, competitive config).

- Tools index: [tools/\_index.md, filter Category = `context`](./tools/_index.md)
- Substrate: `context.summary`, `context.substrate`, `context.query_substrate`, `context.ask`, `context.remember`
- Persisted entries: `context_entries.list`, `context_entries.create`, `context_entries.update`, `context_entries.delete`

### Workflows

Agent and content-creation orchestration. Managed, long-running sessions that produce artifacts.

- Tools index: [tools/\_index.md, filter Category = `workflows`](./tools/_index.md)
- Agents: `agents.start`, `agents.resume`, `agents.cancel`, `agents.run_blueprint`, `agents.fork_blueprint`
- Agent reads (resources, not tools): `agent_profile.list`, `agent_run.get`, `agent_run.list`

### Configuration

API key and OAuth client management.

- Tools index: [tools/\_index.md, filter Category = `configuration`](./tools/_index.md)
- API keys: `api_keys.list`, `api_keys.create`, `api_keys.rotate`, `api_keys.revoke`
- OAuth clients: `oauth_clients.list`, `oauth_clients.get`, `oauth_clients.revoke`

### Platform

Outbound webhook subscriptions and deliveries.

- Tools index: [tools/\_index.md, filter Category = `platform`](./tools/_index.md)
- Key tools: `webhooks.create`, `webhooks.list`, `webhooks.get`, `webhooks.update`, `webhooks.delete`, `webhooks.test_fire`, `webhooks.deliveries`
- Events: [webhook-events.md](./webhook-events.md)

### Observability

Read-only audit log and export.

- Tools index: [tools/\_index.md, filter Category = `observability`](./tools/_index.md)
- Key tools: `audit_log.list`, `audit_log.get`, `audit_log.export`

### Team

Reserved for user and membership management. No tools are exposed on the public surface today; team administration happens through the Amdahl dashboard. This section will populate as team tools ship. Track additions in [../changelog.md](../changelog.md).

## OpenAPI spec

Everything above is also described in a single machine-readable spec:

- JSON: [`openapi.json`](./openapi.json)
- YAML: [`openapi.yaml`](./openapi.yaml)
- Hosted Swagger UI: `https://app.amdahl.co/api/platform/v1/docs`

Generate a typed client from the spec with your favorite toolchain (`openapi-typescript`, `openapi-generator`, `orval`, etc.). The spec is regenerated on every release.

## Scopes

Every tool requires one or more `resource:action` scopes. The full matrix and role defaults are in [scopes.md](./scopes.md). Effective scope is the intersection of credential scopes and role defaults; see [../authentication.md](../authentication.md) for the full policy.

## Data models

Canonical shapes for every response object (artifacts, versions, sessions, agents, webhooks, context entries, deliveries, and more) are in [data-models.md](./data-models.md). That file is generated from the backend Zod schemas and is authoritative.

## Connectors

The full list of connectors a workspace can hook up - each with its connect method, ownership, multi-instance support, puller status, and the data streams it brings in - is in [connector-catalog.md](./connector-catalog.md). That file is generated from the platform connector catalog and is authoritative. For a how-to on connecting a source via the Connections page, the REST API, or MCP, see [../connections/connecting-data-sources.md](../connections/connecting-data-sources.md).

## Webhook events

The full catalogue of emitted webhook events plus payload shapes is in [webhook-events.md](./webhook-events.md). For delivery semantics, signing, and verification, see [../webhooks.md](../webhooks.md).

## Errors

Standard error envelope, code catalogue, HTTP status mapping, and `details` shapes per code are in [errors.md](./errors.md). For retry and idempotency guidance see [../pagination-errors.md](../pagination-errors.md).

## Still looking?

- [Quickstart](../quickstart.md) for a five-minute end-to-end flow.
- [Sessions](../sessions.md) for substrate-accumulating multi-call workflows.
- [Agents](../agents.md) for running managed agents end-to-end.
- [Recipes](../recipes/) for cookbook-style walkthroughs.
- [SDK notes](../sdk/) for curl, TypeScript, and Python idioms.
- [Changelog](../changelog.md) for surface changes and deprecations.