CURL-CALLS.md

Form Fill Agent API - CURL Commands

This document provides detailed curl commands for interacting with the Form Fill Agent API, with real-world examples based on Colorado Springs Utilities and other providers.

Note: For general API documentation and endpoint details, see API-TESTING.md.

Base URL

http://localhost:8000/api/v1

Authentication

All API requests require an API key in the header:

X-API-Key: your_api_key_here

API Endpoints

1. Start Form Filler Agent

Initiates an AI agent to fill out a registration form with the provided user information.

curl -X POST "http://localhost:8000/api/v1/start_agent" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "user_info": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "[email protected]",
      "phone": "555-123-4567",
      "password": "SecurePass123!",
      "username": "johndoe123"
    },
    "starting_url": "https://myaccount.csu.org/eportal/#/startservice?water"
  }'

Response Example:

{
  "message": "Agent started successfully",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

2. Research Form Structure

Analyzes a form at the provided URL and generates a schema of its fields.

curl -X POST "http://localhost:8000/api/v1/research_form" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "provider_id": "173",
    "url": "https://myaccount.csu.org/eportal/#/startservice?water"
  }'

Response Example:

{
  "message": "Form research completed successfully",
  "provider_id": "173",
  "schema": {
    "form_id": "csu-water-registration",
    "total_steps": 3,
    "steps": [
      {
        "step_number": 1,
        "step_title": "Service Information",
        "fields": [
          {
            "type": "text",
            "name": "address",
            "label": "Service Address",
            "required": true,
            "validation": "address format"
          },
          {
            "type": "select",
            "name": "service_type",
            "label": "Service Type",
            "required": true,
            "has_suggestions": true,
            "suggestion_selected": "Water"
          }
        ],
        "navigation": {
          "next": "button.next",
          "back": null
        }
      }
    ],
    "stopping_point": "email verification",
    "errors": null
  }
}

3. Submit User Response

Provides a user's response to a question asked by the agent.

curl -X POST "http://localhost:8000/api/v1/omni-form/response" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_id": "12345",
    "response_data": "123 Main St, Colorado Springs, CO 80903",
    "timestamp": "2024-03-20T10:00:00Z"
  }'

Response Example:

{
  "status": "Answer received"
}

Complete Workflow Examples

Colorado Springs Utilities - Water Service Registration

1. First, research the form structure:

curl -X POST "http://localhost:8000/api/v1/research_form" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "provider_id": "173",
    "url": "https://myaccount.csu.org/eportal/#/startservice?water"
  }'

2. Start the form filling agent:

curl -X POST "http://localhost:8000/api/v1/start_agent" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "user_info": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "[email protected]",
      "phone": "555-123-4567",
      "password": "SecurePass123!",
      "username": "johndoe123"
    },
    "starting_url": "https://myaccount.csu.org/eportal/#/startservice?water"
  }'

3. If the agent asks for additional information, submit your response:

curl -X POST "http://localhost:8000/api/v1/omni-form/response" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_id": "12345",
    "response_data": "123 Main St, Colorado Springs, CO 80903",
    "timestamp": "2024-03-20T10:00:00Z"
  }'

City of Austin Utilities - Water Service Registration

1. Research the form structure:

curl -X POST "http://localhost:8000/api/v1/research_form" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "provider_id": "28",
    "url": "https://coautilities.com/wps/portal/occ/coa/registration/!ut/p/z1/04_Sj9CPykssy0xPLMnMz0vMAfIjo8zi3Q18LDz8nQ18DLw8LAwCDY29PMy9zAyc3Q30w_Ep8A4x0Y8iRr8BDuBoQJx-PAqi8Bsfrh-FzwqwDwiZUZAbGhphkOkIAHHEaE8!/dz/d5/L2dBISEvZ0FBIS9nQSEh/?water"
  }'

2. Start the form filling agent:

curl -X POST "http://localhost:8000/api/v1/start_agent" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "user_info": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "[email protected]",
      "phone": "555-123-4567",
      "password": "SecurePass123!",
      "username": "johndoe123"
    },
    "starting_url": "https://coautilities.com/wps/portal/occ/coa/registration/!ut/p/z1/04_Sj9CPykssy0xPLMnMz0vMAfIjo8zi3Q18LDz8nQ18DLw8LAwCDY29PMy9zAyc3Q30w_Ep8A4x0Y8iRr8BDuBoQJx-PAqi8Bsfrh-FzwqwDwiZUZAbGhphkOkIAHHEaE8!/dz/d5/L2dBISEvZ0FBIS9nQSEh/?water"
  }'

Notes

• Replace your_api_key_here with your actual API key
• The session_id in the response from the start_agent endpoint should be used in subsequent omni-form/response calls
• The request_id for omni-form/response calls will be provided by the agent when it needs additional information
• All timestamps should be in ISO 8601 format
• The API will handle form navigation and filling automatically, only requesting user input when necessary