---
title: "Intent API"
description: "Submit intents, view matches, accept or reject business responses."
canonical: "https://docs.ainative.studio/docs/marketplace/intent-api"
last-updated: "2026-10-26T19:08:16.785Z"
---

# Intent API

Source: https://docs.ainative.studio/docs/marketplace/intent-api

> Submit intents, view matches, accept or reject business responses.

# 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

```bash
POST /api/v1/public/intents
```

**Request Body:**

```json
{
  "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:**

```json
{
  "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

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

Returns all intents for the authenticated user.

## Get Intent Details

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

Returns the intent with all current matches and their statuses.

## Accept or Reject a Match

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

```json
{
  "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

```json
{
  "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` |