Make Agent Fast documentation

API recipes

Automate complete site, agent, knowledge, publish, and reporting workflows.

At a glance

Automate complete site, agent, knowledge, publish, and reporting workflows.

API request pathScoped key → versioned resource → signed response

CreateGroundPublish

These recipes use raw REST so they work before a public SDK is installed. Set MAF_API_KEY in the server environment and replace IDs returned by earlier steps.

Recipe: create and publish a grounded agent#

Create one API key with sites:write, agents:write, and knowledge:write. Add sites:read if the automation also lists or verifies sites.

1. Create the site#

curl --fail-with-body https://makeagent.fast/api/v1/sites \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-site-2026-01" \
  -d '{
    "title": "Acme support",
    "slug": "acme-support",
    "type": "business",
    "template": "minimal",
    "content": {
      "headline": "Ask Acme support",
      "subheadline": "Answers grounded in our current policies.",
      "about": "Acme support answers product and account questions."
    },
    "persona_mode": "assistant",
    "languages": ["en"]
  }'

A successful response is 201 Created, includes the site under data, and returns its canonical resource path in the Location header. Save data.id as SITE_ID.

2. Configure the agent and embed policy#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-agent-2026-01" \
  -d '{
    "display_name": "Acme guide",
    "persona_mode": "assistant",
    "instructions": "Answer only from confirmed Acme sources. If the answer is missing, say that a teammate will follow up.",
    "languages": ["en"],
    "embed_enabled": true,
    "allowed_origins": ["https://www.acme.example", "https://staging.acme.example"]
  }'

Allowed origins are exact origins: scheme, hostname, and optional port. Do not include a path or trailing wildcard.

3. Add a text knowledge source#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/knowledge" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-returns-2026-01" \
  -d '{
    "name": "Returns policy 2026-01",
    "text": "Customers may request a return within 30 days of delivery. Contact support before sending an item back."
  }'

The public API currently ingests pasted text from 5 to 200,000 characters. Use the dashboard for URL crawling, uploads, YouTube, podcast, and feed sources.

4. Add a structured FAQ#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/faqs" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-faq-returns-2026-01" \
  -d '{
    "question": "How long do I have to return an order?",
    "answer": "You may request a return within 30 days of delivery.",
    "approved": true
  }'

5. Publish#

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/publish" \
  -X POST \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-acme-publish-2026-01" \
  -d '{"published": true}'

The response should contain {"data":{"id":"...","status":"published"}}. Open the hosted site and ask a question whose answer appears in the source. Publishing proves the site state changed; it does not prove the source quality or embed origin is correct.

Recipe: paginate leads safely#

Use a key with leads:read. Treat next_cursor as opaque and URL-encode it.

const base = `https://makeagent.fast/api/v1/sites/${siteId}/leads`;
let cursor: string | null = null;

do {
  const url = new URL(base);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.MAF_API_KEY}` },
  });
  if (!response.ok) throw await response.json();

  const page = await response.json();
  for (const lead of page.data) await exportLead(lead);
  cursor = page.next_cursor;
} while (cursor);

Do not decode, edit, sort, or reuse a cursor for a different collection.

Recipe: disable an embed during an incident#

Use agents:write and keep the same idempotency key across network retries:

curl --fail-with-body "https://makeagent.fast/api/v1/sites/$SITE_ID/agent" \
  -X PATCH \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: incident-2026-07-embed-off" \
  -d '{"embed_enabled": false}'

After the response succeeds, verify the launcher no longer initializes on an allowed host. Re-enable it with a new incident-resolution key after correcting the origin, content, or credential problem.

Production checklist#

Use a separate key per service and environment.
Persist resource IDs and idempotency keys before sending a mutation.
Set connect and response timeouts.
Honor Retry-After and cap retries.
Log operation name, HTTP status, and request ID without logging secrets or personal data.
Test against a non-production site before granting write scopes to production.