Formael

Quick Start

Submit your first intent through the Formael gateway in under 5 minutes.

Documentation
3 of 8

Quick Start

This guide gets you from zero to a successfully executed intent in minutes.

Prerequisites

You need a Formael account with at least one agent created and an API key issued. Sign up at app.formael.com if you haven't already.

Step 1: Get your API key

In the Formael dashboard, navigate to Agents and create a new agent. After creation, issue an API key for that agent. Copy the key — it is only shown once.

Your API key looks like:

fml_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Include it on every request to the Agent Plane API as a Bearer token:

Authorization: Bearer fml_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Discover available capabilities

Before submitting an intent, check which capabilities are available in your organization's configuration:

curl https://api.formael.com/agent/v1/capabilities \
  -H "Authorization: Bearer YOUR_API_KEY"

The response lists all available capabilities with their parameter schemas:

{
  "capabilities": [
    {
      "domain": "document-signing",
      "action": "create",
      "entity": "contract",
      "description": "Create a new contract and send it for signing",
      "version": "1.0.0",
      "parameters": {
        "type": "object",
        "required": ["signerName", "signerEmail", "templateId"],
        "properties": {
          "signerName": { "type": "string" },
          "signerEmail": { "type": "string", "format": "email" },
          "templateId": { "type": "string" },
          "subject": { "type": "string" }
        }
      }
    }
  ]
}

Step 3: Submit your first intent

Submit an intent using the capability you just discovered:

curl -X POST https://api.formael.com/agent/v1/intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "document-signing",
    "action": "create",
    "entity": "contract",
    "parameters": {
      "signerName": "Jane Smith",
      "signerEmail": "[email protected]",
      "templateId": "tmpl_mutual_nda",
      "subject": "Mutual NDA — Acme Corp"
    },
    "context": {
      "agentGoal": "Initiate NDA for new vendor partnership with Acme Corp",
      "reasoning": "Contract required before sharing technical specifications"
    }
  }'

The context field is optional but recommended — it becomes part of the permanent audit record and makes your agent's reasoning visible to approvers and compliance teams.

Step 4: Understand the response

Immediate execution (approved)

If the intent passes policy evaluation, execution happens synchronously and you receive the result immediately:

{
  "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
  "outcome": "executed",
  "state": "SUCCEEDED",
  "result": {
    "contractId": "env_2XmZ9kPq...",
    "signingUrl": "https://app.docusign.com/sign/...",
    "status": "sent"
  }
}

Deferred execution (pending human approval)

If the intent triggers a human approval requirement, you receive a receipt immediately — the action is not blocked:

{
  "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
  "outcome": "deferred",
  "state": "PENDING_APPROVAL",
  "estimatedResolution": "2024-01-15T14:30:00Z"
}

Poll for resolution using the iecId:

curl https://api.formael.com/agent/v1/intents/01HX4K2M9V3T7P8Q5N6R0J1W2Y \
  -H "Authorization: Bearer YOUR_API_KEY"

Denied

If the intent is denied by policy, the response includes per-axis reasoning:

{
  "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
  "outcome": "denied",
  "state": "CLOSED",
  "denial": {
    "axis": "fiscal",
    "reason": "Projected cost of $45.00 exceeds the daily agent budget of $10.00",
    "remainingBudget": "$2.13"
  }
}

Next steps

←

Previous

Core Concepts

Next

Submitting Intents
→