attune/docs/api/api-inquiries.md

Inquiry Management API

The Inquiry Management API provides endpoints for managing human-in-the-loop interactions within Attune workflows. Inquiries allow executions to pause and request input from users before continuing, enabling approval workflows, data collection, and interactive automation.

Table of Contents

• Overview
• Inquiry Model
• Authentication
• Endpoints
  • List Inquiries
  • Get Inquiry by ID
  • List Inquiries by Status
  • List Inquiries by Execution
  • Create Inquiry
  • Update Inquiry
  • Respond to Inquiry
  • Delete Inquiry
• Use Cases
• Related Resources

---

Overview

Inquiries represent questions or prompts that require human input during workflow execution. They support:

• Approval Workflows: Request approval before proceeding with critical actions
• Data Collection: Gather additional information from users during execution
• Interactive Automation: Enable dynamic workflows that adapt based on user input
• Assignment: Direct inquiries to specific users or teams
• Timeouts: Automatically expire inquiries after a specified time
• Schema Validation: Define expected response formats using JSON Schema

Key Features

• Status Tracking: Monitor inquiry lifecycle (pending, responded, timeout, canceled)
• Response Validation: Optionally validate responses against JSON schemas
• User Assignment: Assign inquiries to specific users for accountability
• Timeout Handling: Automatically handle expired inquiries
• Execution Integration: Link inquiries to specific workflow executions

---

Inquiry Model

Inquiry Object

{
  "id": 123,
  "execution": 456,
  "prompt": "Approve deployment to production?",
  "response_schema": {
    "type": "object",
    "properties": {
      "approved": {"type": "boolean"},
      "comment": {"type": "string"}
    },
    "required": ["approved"]
  },
  "assigned_to": 789,
  "status": "pending",
  "response": null,
  "timeout_at": "2024-01-15T12:00:00Z",
  "responded_at": null,
  "created": "2024-01-15T10:00:00Z",
  "updated": "2024-01-15T10:00:00Z"
}

Fields

Field	Type	Description
id	integer	Unique inquiry identifier
execution	integer	ID of the execution this inquiry belongs to
prompt	string	Question or prompt text displayed to the user
response_schema	object	Optional JSON Schema defining expected response format
assigned_to	integer	Optional user ID this inquiry is assigned to
status	string	Current status: pending, responded, timeout, canceled
response	object	User's response data (null until responded)
timeout_at	datetime	Optional timestamp when inquiry expires
responded_at	datetime	Timestamp when user responded (null until responded)
created	datetime	Timestamp when inquiry was created
updated	datetime	Timestamp of last update

Inquiry Status

Status	Description
pending	Inquiry is waiting for a response
responded	User has provided a response
timeout	Inquiry expired without receiving a response
canceled	Inquiry was canceled before completion

---

Authentication

All inquiry endpoints require authentication. Include a valid JWT access token in the Authorization header:

Authorization: Bearer <access_token>

See the Authentication Guide for details on obtaining tokens.

---

Endpoints

List Inquiries

Retrieve a paginated list of inquiries with optional filtering.

Endpoint: GET /api/v1/inquiries

Query Parameters:

Parameter	Type	Default	Description
status	string	-	Filter by status (pending, responded, timeout, canceled)
execution	integer	-	Filter by execution ID
assigned_to	integer	-	Filter by assigned user ID
page	integer	1	Page number (1-indexed)
per_page	integer	50	Items per page (max 100)

Example Request:

curl -X GET "http://localhost:8080/api/v1/inquiries?status=pending&page=1&per_page=20" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": [
    {
      "id": 123,
      "execution": 456,
      "prompt": "Approve deployment to production?",
      "assigned_to": 789,
      "status": "pending",
      "has_response": false,
      "timeout_at": "2024-01-15T12:00:00Z",
      "created": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1
  }
}

---

Get Inquiry by ID

Retrieve a single inquiry by its ID.

Endpoint: GET /api/v1/inquiries/:id

Path Parameters:

Parameter	Type	Description
id	integer	Inquiry ID

Example Request:

curl -X GET "http://localhost:8080/api/v1/inquiries/123" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": {
    "id": 123,
    "execution": 456,
    "prompt": "Approve deployment to production?",
    "response_schema": {
      "type": "object",
      "properties": {
        "approved": {"type": "boolean"},
        "comment": {"type": "string"}
      },
      "required": ["approved"]
    },
    "assigned_to": 789,
    "status": "pending",
    "response": null,
    "timeout_at": "2024-01-15T12:00:00Z",
    "responded_at": null,
    "created": "2024-01-15T10:00:00Z",
    "updated": "2024-01-15T10:00:00Z"
  }
}

Error Responses:

• 404 Not Found: Inquiry not found

---

List Inquiries by Status

Retrieve inquiries filtered by status.

Endpoint: GET /api/v1/inquiries/status/:status

Path Parameters:

Parameter	Type	Description
status	string	Status filter: pending, responded, timeout, canceled

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	50	Items per page

Example Request:

curl -X GET "http://localhost:8080/api/v1/inquiries/status/pending" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": [
    {
      "id": 123,
      "execution": 456,
      "prompt": "Approve deployment to production?",
      "assigned_to": 789,
      "status": "pending",
      "has_response": false,
      "timeout_at": "2024-01-15T12:00:00Z",
      "created": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 50,
    "total": 1,
    "total_pages": 1
  }
}

Error Responses:

• 400 Bad Request: Invalid status value

---

List Inquiries by Execution

Retrieve all inquiries associated with a specific execution.

Endpoint: GET /api/v1/executions/:execution_id/inquiries

Path Parameters:

Parameter	Type	Description
execution_id	integer	Execution ID

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	50	Items per page

Example Request:

curl -X GET "http://localhost:8080/api/v1/executions/456/inquiries" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "data": [
    {
      "id": 123,
      "execution": 456,
      "prompt": "Approve deployment to production?",
      "assigned_to": 789,
      "status": "pending",
      "has_response": false,
      "timeout_at": "2024-01-15T12:00:00Z",
      "created": "2024-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 50,
    "total": 1,
    "total_pages": 1
  }
}

Error Responses:

• 404 Not Found: Execution not found

---

Create Inquiry

Create a new inquiry for an execution.

Endpoint: POST /api/v1/inquiries

Request Body:

{
  "execution": 456,
  "prompt": "Approve deployment to production?",
  "response_schema": {
    "type": "object",
    "properties": {
      "approved": {"type": "boolean"},
      "comment": {"type": "string"}
    },
    "required": ["approved"]
  },
  "assigned_to": 789,
  "timeout_at": "2024-01-15T12:00:00Z"
}

Field Validation:

Field	Required	Constraints
execution	Yes	Must be a valid execution ID
prompt	Yes	1-10,000 characters
response_schema	No	Valid JSON Schema object
assigned_to	No	Valid user ID
timeout_at	No	ISO 8601 datetime in the future

Example Request:

curl -X POST "http://localhost:8080/api/v1/inquiries" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "execution": 456,
    "prompt": "Approve deployment to production?",
    "response_schema": {
      "type": "object",
      "properties": {
        "approved": {"type": "boolean"}
      }
    },
    "timeout_at": "2024-01-15T12:00:00Z"
  }'

Response: 201 Created

{
  "data": {
    "id": 123,
    "execution": 456,
    "prompt": "Approve deployment to production?",
    "response_schema": {
      "type": "object",
      "properties": {
        "approved": {"type": "boolean"}
      }
    },
    "assigned_to": null,
    "status": "pending",
    "response": null,
    "timeout_at": "2024-01-15T12:00:00Z",
    "responded_at": null,
    "created": "2024-01-15T10:00:00Z",
    "updated": "2024-01-15T10:00:00Z"
  },
  "message": "Inquiry created successfully"
}

Error Responses:

• 400 Bad Request: Validation error
• 404 Not Found: Execution not found

---

Update Inquiry

Update an existing inquiry's properties.

Endpoint: PUT /api/v1/inquiries/:id

Path Parameters:

Parameter	Type	Description
id	integer	Inquiry ID

Request Body:

{
  "status": "canceled",
  "assigned_to": 999
}

Updatable Fields:

Field	Type	Description
status	string	Update status (any valid status)
response	object	Manually set response data
assigned_to	integer	Change assignment

Example Request:

curl -X PUT "http://localhost:8080/api/v1/inquiries/123" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "canceled"
  }'

Response: 200 OK

{
  "data": {
    "id": 123,
    "execution": 456,
    "prompt": "Approve deployment to production?",
    "response_schema": null,
    "assigned_to": null,
    "status": "canceled",
    "response": null,
    "timeout_at": "2024-01-15T12:00:00Z",
    "responded_at": null,
    "created": "2024-01-15T10:00:00Z",
    "updated": "2024-01-15T10:05:00Z"
  },
  "message": "Inquiry updated successfully"
}

Error Responses:

• 404 Not Found: Inquiry not found
• 400 Bad Request: Validation error

---

Respond to Inquiry

Submit a response to a pending inquiry. This is the primary endpoint for users to answer inquiries.

Endpoint: POST /api/v1/inquiries/:id/respond

Path Parameters:

Parameter	Type	Description
id	integer	Inquiry ID

Request Body:

{
  "response": {
    "approved": true,
    "comment": "Deployment approved for production release v2.1.0"
  }
}

Behavior:

• Only pending inquiries can be responded to
• If inquiry has assigned_to, only that user can respond
• If inquiry has timed out, response is rejected
• Automatically sets status to responded
• Automatically sets responded_at timestamp
• Response should conform to response_schema if defined (future validation)

Example Request:

curl -X POST "http://localhost:8080/api/v1/inquiries/123/respond" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "response": {
      "approved": true,
      "comment": "Looks good, proceeding with deployment"
    }
  }'

Response: 200 OK

{
  "data": {
    "id": 123,
    "execution": 456,
    "prompt": "Approve deployment to production?",
    "response_schema": {
      "type": "object",
      "properties": {
        "approved": {"type": "boolean"},
        "comment": {"type": "string"}
      }
    },
    "assigned_to": 789,
    "status": "responded",
    "response": {
      "approved": true,
      "comment": "Looks good, proceeding with deployment"
    },
    "timeout_at": "2024-01-15T12:00:00Z",
    "responded_at": "2024-01-15T10:30:00Z",
    "created": "2024-01-15T10:00:00Z",
    "updated": "2024-01-15T10:30:00Z"
  },
  "message": "Response submitted successfully"
}

Error Responses:

• 404 Not Found: Inquiry not found
• 400 Bad Request: Inquiry is not in pending status or has timed out
• 403 Forbidden: User is not authorized to respond (inquiry assigned to someone else)

---

Delete Inquiry

Delete an inquiry.

Endpoint: DELETE /api/v1/inquiries/:id

Path Parameters:

Parameter	Type	Description
id	integer	Inquiry ID

Example Request:

curl -X DELETE "http://localhost:8080/api/v1/inquiries/123" \
  -H "Authorization: Bearer <access_token>"

Response: 200 OK

{
  "message": "Inquiry deleted successfully",
  "success": true
}

Error Responses:

• 404 Not Found: Inquiry not found

---

Use Cases

Approval Workflows

Create inquiries to request approval before executing critical actions:

# Create an approval inquiry
curl -X POST "http://localhost:8080/api/v1/inquiries" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "execution": 456,
    "prompt": "Approve deletion of production database backup?",
    "response_schema": {
      "type": "object",
      "properties": {
        "approved": {"type": "boolean"},
        "reason": {"type": "string"}
      },
      "required": ["approved", "reason"]
    },
    "assigned_to": 789,
    "timeout_at": "2024-01-15T18:00:00Z"
  }'

Data Collection

Gather additional information during workflow execution:

# Request deployment details
curl -X POST "http://localhost:8080/api/v1/inquiries" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "execution": 456,
    "prompt": "Enter deployment configuration",
    "response_schema": {
      "type": "object",
      "properties": {
        "environment": {"type": "string", "enum": ["staging", "production"]},
        "replicas": {"type": "integer", "minimum": 1, "maximum": 10},
        "rollback_enabled": {"type": "boolean"}
      },
      "required": ["environment", "replicas"]
    }
  }'

Monitoring Pending Inquiries

List all pending inquiries requiring attention:

# Get all pending inquiries
curl -X GET "http://localhost:8080/api/v1/inquiries?status=pending" \
  -H "Authorization: Bearer <token>"

# Get inquiries assigned to a specific user
curl -X GET "http://localhost:8080/api/v1/inquiries?status=pending&assigned_to=789" \
  -H "Authorization: Bearer <token>"

Responding to Inquiries

Users can respond to assigned inquiries:

curl -X POST "http://localhost:8080/api/v1/inquiries/123/respond" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "response": {
      "environment": "production",
      "replicas": 5,
      "rollback_enabled": true
    }
  }'

---

Best Practices

1. Use Response Schemas

Define clear response schemas to validate user input:

{
  "response_schema": {
    "type": "object",
    "properties": {
      "approved": {"type": "boolean"},
      "justification": {"type": "string", "minLength": 10}
    },
    "required": ["approved", "justification"]
  }
}

2. Set Reasonable Timeouts

Always set timeouts to prevent inquiries from blocking workflows indefinitely:

{
  "timeout_at": "2024-01-15T23:59:59Z"
}

3. Assign to Specific Users

For accountability, assign inquiries to responsible users:

{
  "assigned_to": 789,
  "prompt": "Review and approve security patch deployment"
}

4. Handle Timeouts Gracefully

Monitor inquiries and handle timeout status appropriately in your workflows.

5. Provide Clear Prompts

Write descriptive prompts that clearly explain what information is needed:

{
  "prompt": "The deployment to production requires approval. Review the changes at https://github.com/org/repo/pull/123 and approve or reject."
}

---

Error Handling

Common Error Codes

Status Code	Description
400 Bad Request	Invalid input or inquiry not in correct state
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	User not authorized to respond to inquiry
404 Not Found	Inquiry or execution not found
422 Unprocessable Entity	Validation errors
500 Internal Server Error	Server error

Example Error Response

{
  "error": "Cannot respond to inquiry with status 'responded'. Only pending inquiries can be responded to.",
  "status": 400
}

---

Related Resources

• Execution Management API - Manage workflow executions
• Action Management API - Define executable actions
• Rule Management API - Create automation rules
• Authentication Guide - API authentication details

---

Future Enhancements

Planned Features

1. Response Schema Validation: Automatic validation of responses against JSON Schema
2. Inquiry Templates: Reusable inquiry templates for common patterns
3. Batch Operations: Respond to multiple inquiries at once
4. Notification Integration: Automatic notifications when inquiries are created
5. Audit Trail: Detailed logging of inquiry lifecycle events
6. Custom Actions: Trigger actions on inquiry state changes
7. WebSocket Updates: Real-time inquiry status updates

---

Last Updated: 2024-01-15
API Version: v1