attune-system/attune
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

re-uploading work

Browse Source
This commit is contained in:
David Culbreth
2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

790
docs/api/api-inquiries.md Normal file
View File

@@ -0,0 +1,790 @@
# 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](#overview)
- [Inquiry Model](#inquiry-model)
- [Authentication](#authentication)
- [Endpoints](#endpoints)
- [List Inquiries](#list-inquiries)
- [Get Inquiry by ID](#get-inquiry-by-id)
- [List Inquiries by Status](#list-inquiries-by-status)
- [List Inquiries by Execution](#list-inquiries-by-execution)
- [Create Inquiry](#create-inquiry)
- [Update Inquiry](#update-inquiry)
- [Respond to Inquiry](#respond-to-inquiry)
- [Delete Inquiry](#delete-inquiry)
- [Use Cases](#use-cases)
- [Related Resources](#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
```json
{
"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](./authentication.md) 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:**
```bash
curl -X GET "http://localhost:8080/api/v1/inquiries?status=pending&page=1&per_page=20" \
-H "Authorization: Bearer <access_token>"
```
**Response:** `200 OK`
```json
{
"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:**
```bash
curl -X GET "http://localhost:8080/api/v1/inquiries/123" \
-H "Authorization: Bearer <access_token>"
```
**Response:** `200 OK`
```json
{
"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:**
```bash
curl -X GET "http://localhost:8080/api/v1/inquiries/status/pending" \
-H "Authorization: Bearer <access_token>"
```
**Response:** `200 OK`
```json
{
"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:**
```bash
curl -X GET "http://localhost:8080/api/v1/executions/456/inquiries" \
-H "Authorization: Bearer <access_token>"
```
**Response:** `200 OK`
```json
{
"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:**
```json
{
"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:**
```bash
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`
```json
{
"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:**
```json
{
"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:**
```bash
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`
```json
{
"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:**
```json
{
"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:**
```bash
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`
```json
{
"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:**
```bash
curl -X DELETE "http://localhost:8080/api/v1/inquiries/123" \
-H "Authorization: Bearer <access_token>"
```
**Response:** `200 OK`
```json
{
"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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
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:
```json
{
"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:
```json
{
"timeout_at": "2024-01-15T23:59:59Z"
}
```
### 3. Assign to Specific Users
For accountability, assign inquiries to responsible users:
```json
{
"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:
```json
{
"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
```json
{
"error": "Cannot respond to inquiry with status 'responded'. Only pending inquiries can be responded to.",
"status": 400
}
```
---
## Related Resources
- [Execution Management API](./api-executions.md) - Manage workflow executions
- [Action Management API](./api-actions.md) - Define executable actions
- [Rule Management API](./api-rules.md) - Create automation rules
- [Authentication Guide](./authentication.md) - 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