# Build with Emable

> Internal source material. The customer-facing surface is `docs.emable.ai`
> (generated from `capability_manifest.py`, see `services/docs-site/`) and
> `https://api.emable.ai/docs/build-with-emable.md` (`_BUILD_WITH_EMABLE` in
> `services/emable-api/emable_api/routes/docs.py`). Edit those, not this file,
> for anything a customer or agent will read.

Canonical guide for discovering, quoting, and safely running governed Emable financial intelligence from an application, command line, or AI agent.

## What Emable is for

Emable exposes governed financial capabilities through one product loop:

1. Discover a capability or a complete use case by the outcome needed.
2. Inspect evidence, source freshness, version, provider, dependencies, permissions, limitations, trial policy, charging unit, and maximum run cost.
3. Quote the proposed work before execution.
4. Connect with a least-privilege API key or MCP OAuth grant.
5. Start one explicit run and follow its shared lifecycle.
6. Return the result with citations, actual completed-step charges, and provider settlement recorded by the platform.

Discovery does not imply entitlement or permission to execute. Inventory-only entries never appear as runnable Store capabilities.

## Choose the right surface

| Surface | Best for | Source of truth |
|---|---|---|
| REST | Product integrations, backend services, and web applications | `https://api.emable.ai/openapi-public.json` |
| MCP | AI assistants and coding agents | `https://api.emable.ai/mcp` |
| CLI | Terminal use, CI, inspection, and MCP installation | [`CLI.md`](CLI.md) |
| Markdown | Humans and language models that need a compact integration guide | This file and `https://api.emable.ai/llms-full.txt` |
| Agent skill | A reusable safe-execution policy for supported agents | `https://api.emable.ai/skill.md` |

The API-owned capability and use-case manifests are authoritative for availability and pricing. A frontend card, prompt, cached response, or private Embedded Intelligence registry entry is not an execution contract.

## Recommended workflow

### 1. Discover

Start with `GET /v1/capabilities` when you need a reusable building block. Start with `GET /v1/use-cases` when you need a complete productized outcome composed from multiple steps.

Search the Store by outcome, country, provider, access, status, and pricing. Search use cases by outcome, country, provider, access, status, category, and maximum price.

### 2. Inspect the contract

Read the selected detail response before building around it. Check:

- Semantic version and delivery owner.
- Delivered outcome and input schema.
- Evidence sources and freshness.
- Provider and dependencies.
- Required permissions and supported surfaces.
- Known limitations and human-approval steps.
- Trial rules, charging unit, and exact maximum run cost.
- `runnable`, `execution_enabled`, and any `execution_blocker` returned now.

Do not treat an unavailable public statistic as zero. Public statistics remain hidden until their privacy threshold is satisfied.

### 3. Quote

Use `POST /v1/use-cases/{slug}/quote` or the MCP `quote_use_case` tool before a composed run. A quote:

- Validates the supplied input against the current manifest.
- Returns the manifest version and a one-hour quote ID.
- Returns maximum credits for the complete run and each step.
- States whether human approval is required.
- States whether execution is enabled and why it may be blocked.
- Reserves and charges zero credits.

Do not include secrets or unrelated personal data in quote input. A quote validates input but does not run a capability.

### 4. Authenticate with least privilege

Use an Emable API key for REST or OAuth for MCP. Keep keys on the server side and store them in a secret manager.

REST execution scopes:

| Scope | Allows |
|---|---|
| `capabilities:run` | Start governed capability runs, save configurations, and repeat saved capability configurations. |
| `runs:read` | Read the caller's run records, saved configurations, usage summary, and permitted provider overview. |
| `use-cases:run` | Start a composed use case only when all product and commercial gates are enabled. |

MCP feature-group scopes:

| Scope | Allows |
|---|---|
| `docs:read` | Read public documentation, capabilities, use cases, and free quotes. No customer data. |
| `validator:read` | Read the caller's saved audiences, validation history, and results. |
| `validator:run` | Create audiences and start validations that can spend credits. |

### 5. Execute only on an explicit request

For a capability, call `POST /v1/capabilities/{slug}/runs` with a fresh `Idempotency-Key`. Reuse that key only for an exact retry of the same request.

For a composed use case, call `POST /v1/use-cases/{slug}/runs` only after the user has reviewed the quote and approved the maximum. The endpoint can still refuse execution if the adapter, platform switch, entitlement, balance, or commercial gate is unavailable.

No cron, autonomous outreach, or background content generation starts a run.

### 6. Follow the shared run lifecycle

All supported execution surfaces use the same states:

| State | Meaning | Client behavior |
|---|---|---|
| `queued` | Accepted and waiting for a worker. | Poll the run record. |
| `running` | Work is in progress. | Continue polling without starting another run. |
| `awaiting_approval` | A human decision is required. | Pause and request approval. Never bypass it. |
| `succeeded` | The requested work completed. | Return the result, citations, and completed-step charges. |
| `failed` | Work started but did not complete. | Return the stable error and any safe retry guidance. |
| `refused` | Work was rejected before execution. | Do not retry blindly. No customer charge or provider settlement is created. |

Read records through `GET /v1/runs` or `GET /v1/runs/{run_id}`. A run record can identify its `run_kind`, `use_case_slug`, manifest version, quoted credits, reserved credits, and completed-step charges.

## MCP discovery tools

These seven tools belong to the read-only `docs:read` group. They cannot access customer accounts, production prompts, raw inputs, raw results, identities, or provider settlement data. They do not reserve or charge credits.

### `list_docs`

What it does: lists the public Emable guides, schemas, capability Markdown pages, and use-case Markdown pages.

Use it when: you need to see which documentation exists before selecting a page.

Input: none.

### `search_docs`

What it does: searches public documentation titles and manifest summaries.

Use it when: you know an outcome or topic but not its document, capability, or use-case slug.

Input: `query`, two to 200 characters.

### `get_doc`

What it does: returns one public documentation entry with its title, summary, kind, canonical URL, and related entries.

Use it when: you have a document slug and need the authoritative page to read or cite. Follow the returned URL to read the complete Markdown or schema.

Input: `slug` from `list_docs` or `search_docs`.

### `list_capabilities`

What it does: lists public governed capability contracts, providers, prices, status, and supported execution surfaces.

Use it when: you need a reusable function and want to find candidates by outcome or provider.

Input: optional `query`.

### `get_capability`

What it does: returns one full capability contract, including evidence freshness, permissions, limitations, trial, price, and current run availability.

Use it when: you are deciding whether a capability is suitable and safe before integrating or running it.

Input: capability `slug`.

### `list_use_cases`

What it does: lists public productized outcomes assembled from one or more governed capabilities, including maximum run prices.

Use it when: the user needs an end-to-end outcome rather than a single capability.

Input: optional `query`.

### `quote_use_case`

What it does: validates one use-case input and returns the current maximum price, step breakdown, approval requirement, expiry, and execution blocker.

Use it when: always before requesting approval to start a composed run.

Input: use-case `slug` and an `input` object matching that use case's schema.

Credit behavior: free. `reserved_credits` is zero and no run is created.

## Validator MCP compatibility tools

The original Validator tool names remain supported. These tools operate on the authenticated caller's tenant and are separate from public documentation discovery.

### `list_audiences`

Lists saved audiences with their ID, name, and persona count. Use it first to find the `audience_id` required by audience inspection and validation.

Scope: `validator:read`.

### `get_audience_details`

Returns the selected audience's description, source, creation date, and a preview of up to ten personas. Use it before execution to confirm that the target group is correct.

Scope: `validator:read`.

### `create_audience`

Creates a reusable audience from a name, description, market, and optional size. Use it only when no saved audience matches the intended target group. Creation does not itself start a validation.

Scope: `validator:run`.

### `run_validation`

Starts a 50-persona hypothesis validation against a saved audience and returns a `simulation_id`. Use it only after confirming the hypothesis, audience, market, decision size, and credit spend. The platform checks the full run allowance before work starts and settles actual run usage afterward.

Scope: `validator:run`.

### `get_result`

Polls the `simulation_id` returned by `run_validation`. While running it returns progress. On completion it returns a GO, CONDITIONAL, or NO-GO verdict, confidence, summary, and dashboard link.

Scope: `validator:read`.

### `list_validations`

Lists recent validation runs with their status, verdict, decision size, date, and dashboard link. Use it to find an earlier result or avoid repeating the same hypothesis.

Scope: `validator:read`.

Read-only Validator tool calls are metered connector calls but do not start another validation. Write tools require `validator:run` consent.

## Core REST functions

| Function | What it does | Access and credit behavior |
|---|---|---|
| `GET /v1/capabilities` | Searches public Store capability contracts and returns available filters. | Public and free. Private inventory is excluded. |
| `GET /v1/capabilities/{slug}` | Returns one capability contract and privacy-thresholded statistics. | Public and free. Statistics may be unavailable. |
| `POST /v1/capabilities/{slug}/runs` | Starts one runnable, entitled capability. | `capabilities:run`; can reserve and charge credits; refused work is not charged. |
| `GET /v1/use-cases` | Searches productized use cases and price ceilings. | Public and free. |
| `GET /v1/use-cases/{slug}` | Returns steps, dependencies, limits, price, and current execution blocker. | Public and free. |
| `POST /v1/use-cases/{slug}/quote` | Validates input and returns a one-hour maximum-cost quote. | Public and free; reserves zero credits. |
| `POST /v1/use-cases/{slug}/runs` | Starts a composed run when every gate and adapter is enabled. | `use-cases:run`; can reserve and settle step charges. |
| `GET /v1/runs` | Lists the caller's shared run records. | `runs:read`; tenant-scoped and free to read. |
| `GET /v1/runs/{run_id}` | Returns one caller-owned run and its charges. | `runs:read`; tenant-scoped and free to read. |
| `GET /v1/saved-configurations` | Lists caller-owned reusable configurations. | `runs:read`; tenant-scoped and free to read. |
| `POST /v1/saved-configurations` | Saves a private capability or use-case input. | `capabilities:run`; saving does not execute or charge. |
| `DELETE /v1/saved-configurations/{id}` | Deletes one caller-owned saved configuration. | `capabilities:run`; no execution charge. |
| `POST /v1/saved-configurations/{id}/runs` | Repeats an executable saved capability configuration. | `capabilities:run`; can reserve and charge credits. |
| `GET /v1/usage/summary` | Returns tenant-scoped run counts and credit usage for a period. | `runs:read`; free to read. |
| `GET /v1/provider/overview` | Returns privacy-safe provider aggregates. | `runs:read`; no customer identities, prompts, raw results, or Emable margin. |

Use the public OpenAPI document for complete request and response schemas.

## Error handling

| Status or code | Meaning | Required behavior |
|---|---|---|
| `401 invalid_api_key` | The credential is absent, invalid, expired, or revoked. | Stop and reconnect. |
| `402 insufficient_credits` or `capability_cost_refused` | The account cannot cover the maximum allowed cost. | Do not run. Ask the owner to top up or reduce scope. |
| `403 missing_scope` | The identity lacks the exact required permission. | Request only that scope and reconnect. |
| `409 commercial_validation_required` | The use case has not passed its product gate. | Do not retry or route around the gate. |
| `409 idempotency_conflict` | The key was reused for different input. | Generate a new key for the new request. |
| `422` | Input does not match the current manifest. | Correct it from the returned schema. |
| `503 capability_runs_disabled` | Execution is temporarily off. | Keep discovery available and wait for service restoration. |

Never log or publish raw API keys, OAuth tokens, customer inputs, prompts, named results, or settlement details.

## Install the hosted MCP connector

```bash
# Codex
codex mcp add emable --url https://api.emable.ai/mcp

# Claude Code
claude mcp add --transport http emable https://api.emable.ai/mcp

# Gemini CLI
gemini mcp add -s user -t http emable https://api.emable.ai/mcp

# VS Code
code --add-mcp '{"name":"emable","type":"http","url":"https://api.emable.ai/mcp"}'
```

Generic MCP configuration:

```json
{
  "mcpServers": {
    "emable": {
      "type": "http",
      "url": "https://api.emable.ai/mcp"
    }
  }
}
```

Approve `docs:read` for discovery only. Add `validator:read` or `validator:run` only when the requested work needs tenant data or execution.

## Quote example

```bash
curl -sS https://api.emable.ai/v1/use-cases/european-market-entry-pack/quote \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "company_url": "https://example.com",
      "product_category": "wealthtech",
      "target_adviser_icp": "Independent advisers serving mass affluent clients",
      "candidate_markets": ["DE", "FR"],
      "value_proposition": "Reduce suitability preparation time with governed evidence"
    }
  }'
```

The European Market-Entry Pack has a maximum price of 28,000 credits. Its execution remains disabled until at least one real credit purchase, written implementation commitment, or usable named-buyer implementation-data share satisfies the commercial validation gate. The free quote and aggregate preview remain available. The pack performs no automatic outreach and gives no sales or market-entry-success guarantee.

## Implementation prompt

```text
Use Emable to discover the governed capability or use case that best fits this outcome. Inspect evidence freshness, version, permissions, limitations, and maximum credit cost. Quote before execution. Do not spend credits, expose customer data, or perform outreach without explicit approval. Return citations and actual completed-step charges.
```

## Release status

The contracts in this guide describe the current repository implementation. Production availability must be verified from the live manifest and runtime status before claiming a function is live. The Market-Entry execution gate remains intentionally closed until its commercial condition is met.