Skip to content
Get started

Presets & schemas

#Presets vs. agents vs. versions

A preset is a built-in template (instructions, tools, default models, budget, output schema) the platform ships — GET /v1/presets lists every one the registry knows about:

bash
curl "https://api.agentflowbind.com/v1/presets" -H "Authorization: Bearer afb_live_xxxxxxxxxxxx"
json
{
  "presets": [
    {
      "id": "document/supplier-invoice",
      "family": "document",
      "name": "Supplier Invoice Extraction",
      "description": "Extracts header and line items from a supplier invoice (PDF or image).",
      "inputSpec": { "files": { "accept": ["application/pdf", "image/png", "image/jpeg"], "max": 20 } },
      "outputSchema": { "type": "object", "properties": { "supplier": { "...": "..." }, "total": { "type": "number" } } },
      "budget": { "maxCredits": 300, "maxIterations": 3, "maxDurationMs": 180000 },
      "models": { "control": "claude-opus-5", "act": "claude-sonnet-5" },
      "requiresSchema": false
    }
  ]
}

An agent is your workspace's own named instance of a preset (POST /v1/agents { presetId, name, config? }); each edit to config creates a new immutable version (POST /v1/agents/:id/versions) and becomes the agent's current one. Runs always execute a specific version, never a live-editable "current" pointer that could change mid-run.

#The three document presets

Preset id What it extracts requiresSchema
document/supplier-invoice Header (supplier, invoice number/date, currency, totals) + line items from a supplier invoice No — fixed schema
document/delivery-note Header + shipped line items from a delivery note No — fixed schema
document/custom-form Exactly the fields you define, from any document Yes

#document/supplier-invoice output schema

json
{
  "type": "object",
  "properties": {
    "supplier": { "type": "object", "properties": { "name": { "type": "string" }, "vatId": { "type": "string" }, "address": { "type": "string" } }, "required": ["name"] },
    "invoiceNumber": { "type": "string" },
    "invoiceDate": { "type": "string", "description": "ISO 8601 date" },
    "dueDate": { "type": "string" },
    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "quantity": { "type": "number" },
          "unitPrice": { "type": "number" },
          "amount": { "type": "number" },
          "vatRate": { "type": "number", "description": "Percentage, e.g. 19 for 19%" }
        },
        "required": ["description", "quantity", "unitPrice", "amount"]
      }
    },
    "subtotal": { "type": "number" },
    "vatAmount": { "type": "number" },
    "total": { "type": "number" },
    "paymentReference": { "type": "string" },
    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
    "notes": { "type": "string" }
  },
  "required": ["supplier", "invoiceNumber", "invoiceDate", "currency", "lines", "subtotal", "vatAmount", "total", "confidence"]
}

Every extraction includes a confidence (0–1) and, for scanned/low-quality input, notes explaining what to double-check.

#document/custom-form — bring your own schema

This preset's own outputSchema is a placeholder ({}) — it exists purely so any agent built on it must be created with config.outputSchema set to the fields you actually want:

bash
curl -X POST "https://api.agentflowbind.com/v1/agents" \
  -H "Authorization: Bearer afb_live_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{
    "presetId": "document/custom-form",
    "name": "Purchase order intake",
    "config": {
      "outputSchema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "poNumber": { "type": "string" },
          "vendor": { "type": "string" },
          "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "qty": { "type": "number" } } } }
        },
        "required": ["poNumber", "vendor"]
      }
    }
  }'

Omitting config.outputSchema (or removing it in a later version) returns 400:

json
{ "error": { "code": "schema_required", "message": "Preset \"document/custom-form\" requires a config.outputSchema — this preset's own schema is only a placeholder" } }

#Agent versions

bash
# New version with a tweaked schema — becomes the agent's current version
curl -X POST "https://api.agentflowbind.com/v1/agents/{id}/versions" \
  -H "Authorization: Bearer afb_live_xxxxxxxxxxxx" -H "Content-Type: application/json" \
  -d '{ "config": { "outputSchema": { "...": "updated schema..." } } }'

# List every version, newest first
curl "https://api.agentflowbind.com/v1/agents/{id}/versions" -H "Authorization: Bearer afb_live_xxxxxxxxxxxx"

Every run records which profileVersionId it used — changing an agent's config never retroactively changes what a past run actually did.