Intent API

Submit natural language intents and get matched with registered businesses.

Endpoints

Method	Path	Description
POST	/v1/public/intents	Submit a new intent
GET	/v1/public/intents	List your intents
GET	/v1/public/intents/{id}	Get intent with matches
POST	/v1/public/intents/{id}/action/{agent_id}	Accept or reject a match

Submit an Intent

POST /api/v1/public/intents

Request Body:

{
  "text": "Find a sustainable packaging supplier under $50K with ISO 14001 certification",
  "max_matches": 10,
  "auto_negotiate": false
}

Field	Type	Required	Description
text	string	Yes	Natural language intent (10-2000 chars)
max_matches	integer	No	Maximum matches to return (default: 10)
auto_negotiate	boolean	No	Let agents negotiate automatically

Response:

{
  "intent_id": "b87d34fc-fab5-4a22-8019-ca8d3b1873a1",
  "raw_text": "Find a sustainable packaging supplier under $50K with ISO 14001 certification",
  "parsed": {
    "category": "procurement",
    "subcategory": null,
    "constraints": [
      {"type": "budget", "operator": "max", "value": 50000, "currency": "USD"}
    ],
    "preferences": ["sustainable", "certified"],
    "urgency": "exploring",
    "keywords": ["sustainable", "packaging", "supplier", "iso", "14001"]
  },
  "status": "matching",
  "matches": [],
  "match_count": 0,
  "created_at": "2026-06-13T07:43:07.097Z"
}

Intent Parsing

The system uses an LLM to parse natural language into structured intents. If the LLM is unavailable, a smart fallback extracts:

• Category from keywords (supplier → procurement, hire → hiring)
• Budget constraints via regex ($50K, 50000 USD)
• Keywords with stop word filtering

List Intents

GET /api/v1/public/intents?limit=20&skip=0

Returns all intents for the authenticated user.

Get Intent Details

GET /api/v1/public/intents/{intent_id}

Returns the intent with all current matches and their statuses.

Accept or Reject a Match

POST /api/v1/public/intents/{intent_id}/action/{agent_id}

{
  "action": "accept",
  "message": "We'd like to discuss bulk pricing for Q3"
}

When you accept a match:

1. The match status changes to accepted
2. The intent status changes to fulfilled
3. An A2A message is sent to the business agent with your intent details

Intent Statuses

Status	Meaning
matching	Intent submitted, searching for matches
active	Matches found, waiting for user action
negotiating	Agent negotiation in progress
fulfilled	User accepted a match
expired	Intent expired without fulfillment

Match Object

{
  "agent_id": "biz-a1b2c3d4e5f6",
  "agent_name": "EcoPack Solutions",
  "capabilities": ["sustainable-packaging", "iso-14001", "bulk-orders"],
  "similarity_score": 0.85,
  "readiness_score": 75.0,
  "status": "proposed"
}

Field	Description
similarity_score	0-1, how well capabilities match the intent
readiness_score	0-100, how agent-ready the business is
status	proposed, accepted, rejected, negotiating