# Unformal Developer Resources

> API docs, OpenAPI spec, authentication, webhooks, MCP, and agent integration guides for Unformal.

**URL:** https://unformal.ai/developers
**Updated:** 2026-08-22
**Topics:** Unformal API, OpenAPI, developer, webhooks, Bearer auth, llms.txt

## Summary

Unformal developer resources. REST API base URL https://unformal.ai/api/v1. Human docs at /docs/api, OpenAPI at /openapi.json, machine-readable site index at /llms.txt. Authenticate with Bearer API keys (unf_*) from POST /signup (no auth required). Also: /agents for MCP-style integration, CLI via @unformal/cli, webhooks with HMAC signatures, SSE streaming, and markdown twins for every page (append .md). Assistant guidelines at /ai-info.

---

# Unformal Developer Resources

Everything you need to integrate Unformal programmatically or from an AI agent.

## REST API

| Resource | URL |
| --- | --- |
| Base URL | `https://unformal.ai/api/v1` |
| Human docs | [/docs/api](/docs/api) |
| Markdown docs | [/docs/api.md](/docs/api.md) |
| OpenAPI 3.1 | [/openapi.json](/openapi.json) |
| OpenAPI (alias) | [/api/v1/openapi.json](/api/v1/openapi.json) |

### Authentication

Unformal uses **Bearer API keys**, not OAuth access tokens.

1. `POST /api/v1/signup` with `{"email":"agent@company.com"}` — **no auth required**
2. Store the returned `api_key` (`unf_*`)
3. Send `Authorization: Bearer unf_...` on subsequent requests

Re-auth for existing accounts: `POST /api/v1/login` then `POST /api/v1/login/verify`.

Auth metadata: [/.well-known/oauth-authorization-server](/.well-known/oauth-authorization-server) (documents Bearer keys; not OAuth tokens).

### Error format

All API errors return JSON:

```json
{ "error": { "code": "NOT_FOUND", "message": "Pulse not found", "hint": "..." } }
```

Codes include `UNAUTHORIZED`, `VALIDATION_ERROR`, `NOT_FOUND`, `OUT_OF_CREDITS`, `INTERNAL_ERROR`.

### Quick start

```bash
curl -X POST https://unformal.ai/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@company.com"}'
```

## Agents and MCP

| Resource | URL |
| --- | --- |
| Built for Agents | [/agents](/agents) |
| AI plugin manifest | [/.well-known/ai-plugin.json](/.well-known/ai-plugin.json) |
| Assistant guidelines | [/ai-info](/ai-info) |
| Site index | [/llms.txt](/llms.txt) |
| Full site markdown | [/llms-full.txt](/llms-full.txt) |

Install the Unformal skill for Claude Code:

```bash
mkdir -p ~/.claude/skills/unformal && curl -s https://unformal.ai/SKILL.md > ~/.claude/skills/unformal/SKILL.md
```

## CLI

```bash
npm i -g @unformal/cli
unformal init --key unf_YOUR_KEY
unformal create --intention "Qualify inbound leads"
```

Source: [github.com/Spark-Collective/unformal-skills/cli](https://github.com/Spark-Collective/unformal-skills/tree/master/cli)

## Webhooks and streaming

- Set `webhookUrl` on a Pulse to receive Echo JSON on completion
- Signed with `X-Unformal-Signature` (HMAC-SHA256)
- `GET /api/v1/pulses/:id/stream` — SSE when conversations complete

## Markdown and content negotiation

Every marketing page has a markdown twin:

- Append `.md` to any path (`/pricing.md`, `/compare/tally.md`)
- Or send `Accept: text/markdown` on the HTML URL (returns markdown with `Vary: Accept`)

404 responses include a markdown recovery body pointing at this index, the sitemap, and OpenAPI.

## Contact

Integration questions: [hello@unformal.ai](mailto:hello@unformal.ai) or [/contact](/contact).

## Common questions

### Where is the Unformal API documented?

Human docs: https://unformal.ai/docs/api. OpenAPI: https://unformal.ai/openapi.json. This page indexes all developer resources.

### How do agents authenticate to Unformal?

Bearer API keys (unf_*). Create one with POST https://unformal.ai/api/v1/signup — no prior authentication required.

### Does Unformal publish OpenAPI?

Yes. Fetch https://unformal.ai/openapi.json (canonical). /api/v1/openapi.json mirrors it for clients that expect the spec under the API prefix.

### Where is the Unformal MCP or agent plugin?

https://unformal.ai/.well-known/ai-plugin.json and the /agents page. CLI: @unformal/cli on npm.

### How do I fetch Unformal pages as markdown?

Append .md to any page path, send Accept: text/markdown, or read /llms-full.txt.