Capability Discovery

Capabilities define what your agents can do. The set of capabilities available to your agents is specific to your organization - determined by the Definition Packs you have installed and any customizations you have applied.

Before submitting an intent, use the Capability Discovery API to see what's available and understand the exact parameters each capability expects.

Capability anatomy

Every capability is identified by a three-part tuple:

domain.action.entity

Examples: finance.create.invoice, contracting.sign, identity.provision.account, itsm.escalate.ticket

Your agents use this vocabulary exclusively. The underlying provider is abstracted away.

List all capabilities

Retrieve all capabilities available to your organization, grouped by domain:

GET /agent/v1/capabilities
Authorization: Bearer YOUR_API_KEY

Response:

[
  {
    "domain": "finance",
    "capabilities": [
      {
        "domain": "finance",
        "action": "create",
        "entity": "invoice",
        "version": "1.0.0",
        "description": "Create and send an invoice to a recipient",
        "requiresHitlDefault": false,
        "monetarySensitive": true,
        "reversibility": 0.7
      },
      {
        "domain": "finance",
        "action": "issue",
        "entity": "refund",
        "version": "1.0.0",
        "description": "Issue a refund to a customer",
        "requiresHitlDefault": false,
        "monetarySensitive": true,
        "reversibility": 0.3
      }
    ]
  },
  {
    "domain": "contracting",
    "capabilities": [
      {
        "domain": "contracting",
        "action": "sign",
        "entity": "contract",
        "version": "1.0.0",
        "description": "Send a contract for signature",
        "requiresHitlDefault": true,
        "monetarySensitive": false,
        "reversibility": 0.2
      }
    ]
  }
]

This endpoint returns only capabilities your organization has installed and that have an active provider configured. Capabilities defined in the Platform Catalog but not yet installed in your organization's registry do not appear here.

To browse the full Formael catalog and install additional packs, see Capability Catalog & Definition Packs.

Understanding requiresHitlDefault

When requiresHitlDefault: true, the capability triggers human approval by default - regardless of your configured risk threshold. This applies to high-stakes operations like contracting.sign, identity.deprovision.account, and identity.grant.role.

The requiresHitlDefault value reflects your organization's configuration for this capability. It may differ from the pack's default if your organization has adjusted it.

Get a single capability schema

Retrieve the full parameter schema for a specific capability:

GET /agent/v1/capabilities/{domain}/{action}/{entity}
Authorization: Bearer YOUR_API_KEY

Example:

GET /agent/v1/capabilities/finance/create/invoice

Response:

{
  "domain": "finance",
  "action": "create",
  "entity": "invoice",
  "version": "1.0.0",
  "description": "Create and send an invoice to a recipient",
  "parameters": {
    "type": "object",
    "required": ["recipientEmail", "amount", "currency"],
    "properties": {
      "recipientEmail": {
        "type": "string",
        "format": "email",
        "description": "Email address of the invoice recipient"
      },
      "amount": {
        "type": "number",
        "minimum": 0,
        "description": "Invoice amount"
      },
      "currency": {
        "type": "string",
        "enum": ["USD", "EUR", "GBP"],
        "description": "Three-letter ISO currency code"
      },
      "dueDate": {
        "type": "string",
        "format": "date",
        "description": "Invoice due date"
      },
      "description": {
        "type": "string",
        "description": "Line item description"
      }
    }
  },
  "returns": {
    "type": "object",
    "properties": {
      "invoiceId": { "type": "string" },
      "invoiceUrl": { "type": "string" },
      "status": { "type": "string", "enum": ["draft", "sent", "paid"] }
    }
  },
  "riskProfile": {
    "reversibility": 0.7,
    "monetarySensitive": true,
    "piiSensitive": false,
    "requiresHitlDefault": false
  }
}

The schema returned is your organization's version of this capability. If your organization has added custom fields or adjusted the risk profile, those changes are reflected here.

Get a standalone parameter schema

For agent frameworks that accept JSON Schema tool definitions directly:

GET /agent/v1/capabilities/{domain}/{action}/{entity}/schema
Authorization: Bearer YOUR_API_KEY

Returns just the parameters JSON Schema document - ready to use as a function-calling tool definition.

Building agent prompts with capability schemas

A common pattern is to include the capability schema in your agent's context so it knows exactly what parameters to provide:

# Fetch schemas for capabilities your agent might use
capabilities = client.capabilities.list_by_domain("finance")
schema_context = format_as_tool_definitions(capabilities)
# Pass schema_context into your agent's system prompt

Because schemas are JSON Schema documents, they can be passed directly to function-calling models as tool definitions.

Agents built against one organization's capability schemas should always rediscover capabilities when used with a different organization - each organization configures its own definitions.

Capability versioning

Capabilities are versioned. The version field tells you which version your organization is running. When your organization accepts a pack upgrade that changes a capability's schema, the version is incremented.

Existing intents are always resolved against the version that was active when they were submitted. Upgrades do not retroactively affect historical IEC records.