# Zapini API — AI Functions

Manage AI functions (webhook-based tools) that your AI agent can call during conversations. Create, configure, test, and monitor custom functions that extend your AI agent's capabilities.

**Requirement:** An active AI Agent integration on your account.

**Base URL:** `https://zapini.app/api/v1`

**Authentication:** `Authorization: Bearer {token}`

---

## Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/ai-functions` | List all AI functions |
| POST | `/ai-functions` | Create a new AI function |
| GET | `/ai-functions/executions/{uuid}` | Get execution details |
| GET | `/ai-functions/{uuid}` | Get AI function details |
| PUT | `/ai-functions/{uuid}` | Update AI function |
| DELETE | `/ai-functions/{uuid}` | Delete AI function |
| POST | `/ai-functions/{uuid}/toggle` | Toggle enabled/disabled |
| POST | `/ai-functions/{uuid}/test` | Test function execution |
| GET | `/ai-functions/{uuid}/executions` | List function executions |

---

## List AI Functions

```
GET /api/v1/ai-functions
```

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `integration_uuid` | string | Filter by integration UUID |
| `type` | string | Filter by type: `fetch_data`, `collect_submit`, `action` |
| `enabled` | boolean | Filter by enabled status |
| `search` | string | Search by name or description |
| `per_page` | integer | Results per page (max 100, default 20) |

**Example:**

```bash
curl -X GET "https://zapini.app/api/v1/ai-functions?type=fetch_data&enabled=true" \
  -H "Authorization: Bearer {token}"
```

---

## Create AI Function

```
POST /api/v1/ai-functions
```

**Body Parameters:**

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| `integration_uuid` | Yes | string | UUID of the AI Agent integration |
| `name` | Yes | string | Function name (lowercase, underscores only) |
| `display_name` | Yes | string | User-friendly display name |
| `description` | Yes | string | Description shown to the AI agent |
| `type` | Yes | string | `fetch_data`, `collect_submit`, or `action` |
| `endpoint_url` | No | string | Webhook URL to call |
| `http_method` | No | string | GET, POST, PUT, PATCH, DELETE |
| `auth_type` | No | string | none, bearer, basic, api_key, custom |
| `auth_config` | No | object | Authentication credentials |
| `headers` | No | object | Custom HTTP headers |
| `request_body_template` | No | object | Request body template |
| `response_mapping` | No | object | Response field mapping |
| `success_message` | No | string | Message on success |
| `error_message` | No | string | Message on error |
| `requires_confirmation` | No | boolean | Ask user confirmation before executing |
| `timeout` | No | integer | Timeout in seconds (1-120) |
| `max_retries` | No | integer | Max retry attempts (0-5) |
| `is_enabled` | No | boolean | Whether function is active |
| `priority` | No | integer | Execution priority (0-100) |
| `parameters` | No | array | Array of function parameters |

**Parameter Object:**

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `name` | Yes | string | Parameter name |
| `display_name` | Yes | string | Display name |
| `description` | No | string | Description for AI |
| `type` | Yes | string | string, number, integer, boolean, email, phone, cpf, cnpj, date, datetime, select, multi_select |
| `is_required` | No | boolean | Whether required |
| `options` | No | array | Options for select types |
| `collect_from_user` | No | boolean | Collect from user in chat |
| `collect_from_context` | No | boolean | Extract from context |

**Example:**

```bash
curl -X POST "https://zapini.app/api/v1/ai-functions" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_uuid": "abc-123-def",
    "name": "check_order_status",
    "display_name": "Check Order Status",
    "description": "Checks the status of a customer order by order number",
    "type": "fetch_data",
    "endpoint_url": "https://api.myshop.com/orders/status",
    "http_method": "GET",
    "auth_type": "bearer",
    "auth_config": {"token": "my-shop-api-key"},
    "parameters": [
      {
        "name": "order_number",
        "display_name": "Order Number",
        "description": "The customer order number",
        "type": "string",
        "is_required": true,
        "collect_from_user": true
      }
    ]
  }'
```

---

## Get AI Function

```
GET /api/v1/ai-functions/{uuid}
```

Returns function details with parameters and execution stats (execution count, last executed, 30-day success rate).

---

## Update AI Function

```
PUT /api/v1/ai-functions/{uuid}
```

Same parameters as Create. If `parameters` array is provided, all existing parameters are replaced.

---

## Delete AI Function

```
DELETE /api/v1/ai-functions/{uuid}
```

Fails with `409 ACTIVE_EXECUTIONS` if there are active executions in progress.

---

## Toggle AI Function

```
POST /api/v1/ai-functions/{uuid}/toggle
```

Toggles the `is_enabled` state.

---

## Test AI Function

```
POST /api/v1/ai-functions/{uuid}/test
```

**Body:**

```json
{
  "parameters": {
    "order_number": "ORD-12345"
  }
}
```

Executes a test call to the function's endpoint and returns the result.

---

## List Executions

```
GET /api/v1/ai-functions/{uuid}/executions
```

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Filter: pending, collecting, executing, completed, failed, timeout |
| `per_page` | integer | Results per page (max 100, default 20) |

---

## Get Execution Details

```
GET /api/v1/ai-functions/executions/{uuid}
```

Returns full execution details including request/response data, parameters collected, and timing information.

---

## Error Codes

| Code | HTTP | Description |
|------|------|-------------|
| `AI_AGENT_NOT_ENABLED` | 403 | No active AI Agent integration |
| `DUPLICATE_NAME` | 422 | Function name already exists in integration |
| `ACTIVE_EXECUTIONS` | 409 | Cannot delete while executions are in progress |
| `INVALID_INTEGRATION_TYPE` | 422 | Integration is not of AI Agent type |
| `TEST_FAILED` | 500 | Test execution failed |