Skip to content

Commit 95c158a

Browse files
robertjdominguezrobertjdominguez
committed
Docs: Add API docs for scheduling, etc. (#214)
## Description 📝 Comprehensive documentation update for new Scheduling and User Artifacts APIs: - Reorganized authentication documentation with expanded API coverage - Added complete User Artifacts API documentation with file management capabilities - Enhanced Threads v2 API documentation with artifact handling and user confirmation workflows Previously, the authentication docs only covered basic thread and automation operations: ````mdx path=docs/promptql-apis/auth.mdx mode=EXCERPT - **Threads API**: Thread management, sharing, and pinned threads - **Automations API**: Automation management (create, list, get, delete) ```` Now we have comprehensive coverage of all user-scoped operations including the new APIs: ````mdx path=docs/promptql-apis/auth.mdx mode=EXCERPT - **Threads API**: Thread management, sharing, pinned threads, and v2 endpoints - **Automations API**: Automation management (create, list, get, delete) - **Schedules API**: Schedule management (create, list, get, update, delete) - **User Artifacts API**: File upload, management, and download operations - **Autograph Requests API**: Approval workflow management ```` The User Artifacts API introduces a complete file management system with binary upload support, versioning, visibility controls, and comprehensive CRUD operations. This fills a critical gap for developers who need to handle file uploads and downloads within their PromptQL applications. The enhanced Threads v2 documentation now includes detailed coverage of artifact handling, user confirmation workflows, and advanced thread management - making it clear how the new v2 endpoints differ from the original thread API and when to use each approach. ## Quick Links 🚀 [API Docs](https://robdominguez-doc-3135-update.promptql-docs.pages.dev/promptql-apis/)
1 parent b906a2b commit 95c158a

File tree

7 files changed

+972
-4
lines changed

7 files changed

+972
-4
lines changed

‎docs/promptql-apis/auth.mdx‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 7
2+
sidebar_position: 9
33
sidebar_label: Authentication in APIs
44
description: ""
55
keywords:
@@ -23,8 +23,11 @@ PromptQL APIs use two distinct authentication approaches:
2323

2424
These operations manage user-owned resources and require JWT authentication:
2525

26-
- **Threads API**: Thread management, sharing, and pinned threads
26+
- **Threads API**: Thread management, sharing, pinned threads, and v2 endpoints
2727
- **Automations API**: Automation management (create, list, get, delete)
28+
- **Schedules API**: Schedule management (create, list, get, update, delete)
29+
- **User Artifacts API**: File upload, management, and download operations
30+
- **Autograph Requests API**: Approval workflow management
2831

2932
**Authentication Method**: JWT Bearer token obtained through the PromptQL token refresh endpoint
3033

‎docs/promptql-apis/autograph-requests-api.mdx‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
---
2+
sidebar_position: 8
3+
sidebar_label: Autograph Requests API
4+
description: "Learn how to manage approval workflows and autograph requests for sensitive operations."
5+
keywords:
6+
- hasura ddn
7+
- autograph requests
8+
- apis
9+
- approval workflow
10+
- permissions
11+
toc_max_heading_level: 3
12+
---
13+
14+
import Tabs from "@theme/Tabs";
15+
import TabItem from "@theme/TabItem";
16+
17+
# Autograph Requests API
18+
19+
## Introduction
20+
21+
The Autograph Requests API provides approval workflow functionality for sensitive operations that require administrative
22+
approval before execution. This API allows collaborators to request permissions for specific actions and enables
23+
administrators to review, approve, or deny these requests.
24+
25+
## Base URL
26+
27+
Autograph Requests endpoints use the following base URL:
28+
29+
`https://promptql.ddn.hasura.app/autograph-requests/`
30+
31+
:::note Private DDN Endpoint
32+
33+
For Private DDN setups the endpoint will change to use the fully qualified domain name (FQDN) for the project assigned
34+
by the control plane. For example:
35+
36+
`https://promptql.<FQDN>/autograph-requests/`
37+
38+
**You can find your API endpoint in the project's settings under `PromptQL API Endpoint`.**
39+
40+
:::
41+
42+
## Authentication
43+
44+
Autograph Requests endpoints require JWT authentication for all operations:
45+
46+
```
47+
Authorization: Bearer <jwt-token>
48+
Content-Type: application/json
49+
```
50+
51+
:::info Getting JWT Tokens
52+
53+
For information on obtaining JWT tokens, see the
54+
[Authentication guide](/promptql-apis/auth.mdx#getting-jwt-tokens-for-user-scoped-operations).
55+
56+
:::
57+
58+
## Access Control
59+
60+
The Autograph Requests API implements role-based access control:
61+
62+
### Admin Users
63+
64+
- Can view all requests for the project
65+
- Can approve or deny requests
66+
- Can update request status and add admin notes
67+
68+
### Collaborator Users
69+
70+
- Can only view their own requests
71+
- Cannot update request status
72+
- Can create new requests (through other APIs that trigger approval workflows)
73+
74+
## List Autograph Requests
75+
76+
Retrieve autograph requests with optional filtering.
77+
78+
`GET /autograph-requests/`
79+
80+
### Query Parameters
81+
82+
| Parameter | Type | Required | Description |
83+
| ------------------- | ------ | -------- | ------------------------------------------------- |
84+
| `thread_id` | string | No | Filter by thread ID (UUID format) |
85+
| `status` | string | No | Filter by status: "pending", "approved", "denied" |
86+
| `requestor_user_id` | string | No | Filter by requestor user ID (admin only) |
87+
| `updated_by` | string | No | Filter by user who updated the request |
88+
89+
### Response
90+
91+
```json
92+
{
93+
"requests": [
94+
{
95+
"autograph_request_id": "123e4567-e89b-12d3-a456-426614174000",
96+
"thread_id": "thread-uuid",
97+
"requestor_user_id": "user-uuid",
98+
"status": "pending",
99+
"request_type": "data_modification",
100+
"description": "Request to modify customer data",
101+
"created_at": "2024-01-15T10:30:00Z",
102+
"updated_at": "2024-01-15T10:30:00Z",
103+
"updated_by": null,
104+
"admin_notes": null
105+
}
106+
],
107+
"total_count": 1
108+
}
109+
```
110+
111+
### Response Fields
112+
113+
| Field | Type | Description |
114+
| ---------------------- | ------ | ----------------------------------------------- |
115+
| `autograph_request_id` | string | Unique identifier for the request |
116+
| `thread_id` | string | Associated thread ID |
117+
| `requestor_user_id` | string | ID of the user who made the request |
118+
| `status` | string | Current status: "pending", "approved", "denied" |
119+
| `request_type` | string | Type of operation being requested |
120+
| `description` | string | Human-readable description of the request |
121+
| `created_at` | string | ISO 8601 timestamp of creation |
122+
| `updated_at` | string | ISO 8601 timestamp of last update |
123+
| `updated_by` | string | ID of admin who last updated the request |
124+
| `admin_notes` | string | Optional notes from the reviewing admin |
125+
126+
### Error Responses
127+
128+
- `403 Forbidden` - User lacks access to the project
129+
- `404 Not Found` - Project not found
130+
131+
## Get Autograph Request
132+
133+
Retrieve a specific autograph request by its ID.
134+
135+
`GET /autograph-requests/{autograph_request_id}`
136+
137+
### Path Parameters
138+
139+
| Parameter | Type | Required | Description |
140+
| ---------------------- | ------ | -------- | ------------------------------- |
141+
| `autograph_request_id` | string | Yes | UUID of the request to retrieve |
142+
143+
### Response
144+
145+
```json
146+
{
147+
"autograph_request_id": "123e4567-e89b-12d3-a456-426614174000",
148+
"thread_id": "thread-uuid",
149+
"requestor_user_id": "user-uuid",
150+
"status": "pending",
151+
"request_type": "data_modification",
152+
"description": "Request to modify customer data in the analytics table",
153+
"request_details": {
154+
"table_name": "customer_analytics",
155+
"operation": "UPDATE",
156+
"affected_rows": 150,
157+
"columns": ["last_login", "status"]
158+
},
159+
"created_at": "2024-01-15T10:30:00Z",
160+
"updated_at": "2024-01-15T10:30:00Z",
161+
"updated_by": null,
162+
"admin_notes": null,
163+
"requestor_info": {
164+
"user_id": "user-uuid",
165+
"email": "[email protected]",
166+
"name": "John Doe"
167+
}
168+
}
169+
```
170+
171+
### Error Responses
172+
173+
- `403 Forbidden` - User lacks access to this request
174+
- `404 Not Found` - Request not found
175+
176+
## Update Autograph Request
177+
178+
Update the status of an autograph request (admin only).
179+
180+
`PATCH /autograph-requests/{autograph_request_id}`
181+
182+
### Path Parameters
183+
184+
| Parameter | Type | Required | Description |
185+
| ---------------------- | ------ | -------- | ----------------------------- |
186+
| `autograph_request_id` | string | Yes | UUID of the request to update |
187+
188+
### Request Body
189+
190+
```json
191+
{
192+
"status": "approved",
193+
"admin_notes": "Approved after reviewing the data modification requirements. Please proceed with caution."
194+
}
195+
```
196+
197+
### Request Fields
198+
199+
| Field | Type | Required | Description |
200+
| ------------- | ------ | -------- | -------------------------------------- |
201+
| `status` | string | Yes | New status: "approved" or "denied" |
202+
| `admin_notes` | string | No | Optional notes explaining the decision |
203+
204+
### Response
205+
206+
```json
207+
{
208+
"autograph_request_id": "123e4567-e89b-12d3-a456-426614174000",
209+
"thread_id": "thread-uuid",
210+
"requestor_user_id": "user-uuid",
211+
"status": "approved",
212+
"request_type": "data_modification",
213+
"description": "Request to modify customer data in the analytics table",
214+
"created_at": "2024-01-15T10:30:00Z",
215+
"updated_at": "2024-01-15T14:30:00Z",
216+
"updated_by": "admin-user-uuid",
217+
"admin_notes": "Approved after reviewing the data modification requirements. Please proceed with caution."
218+
}
219+
```
220+
221+
### Error Responses
222+
223+
- `403 Forbidden` - User lacks admin access to update requests
224+
- `404 Not Found` - Request not found
225+
- `422 Unprocessable Entity` - Invalid status or validation errors
226+
227+
## Request Types
228+
229+
The following request types are supported:
230+
231+
### Data Modification
232+
233+
- **Type**: `data_modification`
234+
- **Description**: Requests to modify, insert, or delete data
235+
- **Common scenarios**: Updating customer records, bulk data changes
236+
237+
### Schema Changes
238+
239+
- **Type**: `schema_modification`
240+
- **Description**: Requests to modify database schema
241+
- **Common scenarios**: Adding columns, creating tables, altering constraints
242+
243+
### Sensitive Operations
244+
245+
- **Type**: `sensitive_operation`
246+
- **Description**: Operations that require special approval
247+
- **Common scenarios**: Data exports, system configuration changes
248+
249+
### Custom Operations
250+
251+
- **Type**: `custom`
252+
- **Description**: Project-specific operations requiring approval
253+
- **Common scenarios**: Custom workflows, integrations

‎docs/promptql-apis/index.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,15 @@ powered by Hasura DDN.
3434
- **[Automations API](/promptql-apis/automations-api.mdx)** - Create, manage, and execute automations that can process
3535
table data with simplified input formats. Perfect for building automated workflows and data processing pipelines.
3636

37+
- **[Schedules API](/promptql-apis/schedules-api.mdx)** - Create and manage scheduled executions of automations and
38+
recurring tasks. Set up automated workflows that run at specific times or intervals using cron expressions.
39+
40+
- **[User Artifacts API](/promptql-apis/user-artifacts-api.mdx)** - Upload, manage, and download files and artifacts
41+
within your PromptQL projects. Supports binary data upload with metadata, versioning, and visibility controls.
42+
43+
- **[Autograph Requests API](/promptql-apis/autograph-requests-api.mdx)** - Manage approval workflows for sensitive
44+
operations. Enables administrators to review, approve, or deny requests from collaborators for protected actions.
45+
3746
- **[System APIs](/promptql-apis/system-apis.mdx)** - Utility endpoints for health checks, version information, and
3847
capability discovery. Essential for monitoring, debugging, and understanding your PromptQL instance.
3948

0 commit comments

Comments
 (0)