Skip to content

Unformal Developer Resources

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

Last updated

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
Markdown docs /docs/api.md
OpenAPI 3.1 /openapi.json
OpenAPI (alias) /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 (documents Bearer keys; not OAuth tokens).

Error format

All API errors return JSON:

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

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

Quick start

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
AI plugin manifest /.well-known/ai-plugin.json
Assistant guidelines /ai-info
Site index /llms.txt
Full site markdown /llms-full.txt

Install the Unformal skill for Claude Code:

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

CLI

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

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 or /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.

Reading this as an agent? Fetch /developers.md for clean markdown, or /llms.txt for the whole site.