# Build with AI

This documentation, and this API, are built to be read by a model as well as by you. Two of the three things on this page work right now with nothing installed.

## The whole site as text

Every page here is also served as Markdown — the same words, no markup — at the page's own address with `.md` on the end. And `llms.txt` is the index of all of them.

**Shell**

```bash
# The index: every page, with a sentence saying what is on it.
curl -s https://voice.sphoro.com/docs/llms.txt

# One page, as plain Markdown.
curl -s https://voice.sphoro.com/docs/agents.md
```

Paste one into a model, diff them between releases, or point a coding assistant's fetch tool at them. Nothing needs to be installed and no credential is required.

## The API as a machine-readable description

**Shell**

```bash
curl -s https://voice.sphoro.com/openapi.json
curl -s https://voice.sphoro.com/openapi.yaml
```

Generated by the running server, so it describes the deployment you are actually talking to rather than a snapshot somebody exported. Most code generators take it directly, and most coding assistants will read it if you hand them the URL. See [API reference](https://voice.sphoro.com/docs/reference).

> **Give an assistant both.** The OpenAPI document tells it which fields exist; the Markdown pages tell it which combinations are sensible. On its own, the schema will happily produce an agent with a `keypad` map, no greeting, and nothing to read the menu out.

## The MCP server

Sphoro Voice speaks the Model Context Protocol, which gives a coding assistant real hands on your account: it can create agents, place and inspect calls, manage knowledge bases, test post-call extraction, build and validate journeys, inject events into live flows, and read these docs — with the same API key you would use yourself.

> **The MCP server is a binary provided with your account.** [Ask us](https://voice.sphoro.com/docs/support) for the build for your platform. Once you have it, point any MCP client at it with your key in the environment — the client's own documentation covers how to add a server.

Roughly fifty tools, in the shape of the API rather than a reduction of it:

| Area | What the assistant can do |
| --- | --- |
| Agents | Create, read, update, delete; list the templates; extract a persona from one. |
| Calls | Start one, read it, fetch the transcript, end it, inject an event into a live flow. |
| Knowledge | Create a base, ingest text or a URL, search it, list and delete. |
| Journeys | Create, save and validate a draft, publish it, start an execution, read one, cancel it. |
| Campaigns | Create, add contacts, start, pause, resume, cancel, read the report. |
| Post-call | Test an extraction against a transcript without placing a call. |
| Webhooks | Create an endpoint, list them, send a test delivery. |
| Compliance | Check a number, add a suppression. |
| Analytics | Read the overview. |
| Docs | Search and fetch these pages, so it answers from the current version rather than from training data. |

Which turns a session into: *"Create a Hindi-first collections agent that verifies date of birth before naming the amount, then test-call my number"*, or *"Why did call `call_8b21…` end so fast?"*, or *"Add an extraction for whether the caller agreed to the plan, and try it on the last three transcripts."*

## Skills

Task-shaped instructions for a coding assistant — the method rather than the hands. The MCP server lets an assistant call the API; the skills tell it what a good agent body looks like, how to write an extraction that answers reliably, and which field to check for each symptom.

| Skill | Teaches |
| --- | --- |
| Authenticating | Base URLs, keys, and what a 401, 403 or 429 actually means. |
| Creating an agent | The body end to end: languages, conversation settings, post-call, tools, modes. |
| Making a call | Placing and following one; variables, compliance, end reasons. |
| Inbound setup | Pointing a number at an agent, menus, capacity. |
| Post-call extraction | Designing fields that come back right, and testing them. |
| Building a flow | Nodes, edges, expressions, capture, injected events. |
| Building a journey | Call, branch, wait, retry, message; drafts and versions. |
| Prompt writing | The structure, and the rules for text that is read aloud. |
| Debugging calls | Symptom to field: end reasons, latency, barge-in, flows, webhooks. |
| Webhooks | Subscribing, verifying signatures, retries, dedupe. |
| Campaigns and compliance | Lists, pacing, suppression, consent, calling windows. |

> The skills pack is distributed with your account alongside the MCP server. [Ask us](https://voice.sphoro.com/docs/support) for it.

## What to tell an assistant first

With no tooling at all, this is usually enough to get a useful first draft:

```
Read https://voice.sphoro.com/docs/llms.txt and then the pages it lists for agents,
prompting and post-call. The API description is at https://voice.sphoro.com/openapi.json.

Then write me a POST /v1/agents body for an outbound appointment-reminder
agent that speaks Hindi first and English second, leaves a voicemail message,
and extracts whether the appointment was confirmed.
```

> **Have it place the first call to your own number.** An assistant with an API key and a phone number is an assistant that can ring a stranger. Every example on this site dials a number you control, for that reason.