jacob-mathison/query-orchestration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity

Merged in feature/local-pdp (pull request #208)

Browse Source 
permit.io local pdp

* docs and testing

* build fix

* docs

* permit rights

* accept self signed certs

* fix eula error
This commit is contained in:
Jay Brown
2026-02-12 23:46:53 +00:00
parent 963ccc6553
commit d7f6c3700b
14 changed files with 1269 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai.generated/03-api-documentation.md
+99 -123
View File
@@ -24,7 +24,6 @@ The API is organized into the following service groups:
| FolderService | Operations related to document folders and organization |
| LabelService | Operations related to document labels and workflow tracking |
| FieldExtractionService | Operations related to document field extractions |
| QueryService | Operations related to queries |
| ExportService | Operations related to exports |
| AuthService | Operations related to authentication |
| AdminService | Operations related to user management and administration |
@@ -81,6 +80,34 @@ Returns the HTML menu page for authenticated users.
**Security**: Requires JWT authentication
**Response**: `200` HTML content
#### `GET /identity`
Returns the authenticated user's assigned roles from Permit.io, including the permissions granted by each role. Any authenticated user can call this endpoint to discover their own roles. This endpoint requires JWT authentication but does not require specific Permit.io permissions.
**Security**: Requires JWT authentication (auth-only, no Permit.io check)
**Response** (`IdentityResponse`):
```json
{
"roles": [
{
"key": "auditor",
"name": "Auditor",
"description": "Read-only access to view documents and exports",
"permissions": ["document:read", "document:list", "export:read"]
}
]
}
```
**Responses**:
- `200`: User roles and permissions retrieved successfully
- `401`: Authentication required
- `429`: Rate limit exceeded
- `502`: Failed to retrieve roles from Permit.io
## Rate Limiting
The queryAPI service implements dual-layer rate limiting to protect against DDoS attacks and ensure fair resource allocation.
@@ -153,6 +180,27 @@ RateLimit: 20;window=2
## Client Management (ClientService)
### `GET /clients`
Lists all clients in the system.
**Security**: Requires JWT authentication
**Response** (`ClientListResponse`):
```json
{
"clients": [
{
"id": "AAA",
"name": "ACME Corporation",
"can_sync": true
}
],
"totalCount": 1
}
```
### `POST /client`
Creates a new client in the system.
@@ -272,7 +320,7 @@ Lists documents for a client.
### `GET /document/{id}`
Retrieves document details by ID.
Retrieves enriched document details by ID, including metadata such as folder, filename, labels, and optionally the full text extraction record.
**Security**: Requires JWT authentication
@@ -280,17 +328,31 @@ Retrieves document details by ID.
- `id`: Document UUID (max 36 chars)
**Response** (`Document`):
**Query Parameters**:
- `textRecord` (optional, default: false): When true, includes the full text extraction record in the response
**Response** (`DocumentEnriched`):
```json
{
"id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
"client_id": "AAA",
"hash": "sha256:abc123...",
"fields": {
"property1": "string value",
"property2": 42
}
"hasTextRecord": true,
"folderId": "019580df-ef65-7676-8de9-94435a93337a",
"filename": "contract_2024.pdf",
"originalPath": "/documents/2024/contract_2024.pdf",
"labels": [
{
"id": "019580df-ef65-7676-8de9-94435a93337b",
"documentId": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
"label": "OCR_Processed",
"appliedBy": "user@example.com",
"appliedAt": "2025-10-16T14:27:15Z"
}
],
"fileSizeBytes": 1048576
}
```
@@ -450,6 +512,10 @@ Lists all folders for a specific client, including the folder hierarchy.
- `clientId`: Client external ID (string, max 36 chars)
**Query Parameters**:
- `metrics` (optional, default: false): When true, includes processing metrics for each folder (document counts by label). Adds overhead so should only be used when metrics are needed.
**Response** (`200 OK`):
```json
@@ -548,10 +614,14 @@ Renames an existing folder.
### `GET /folders/{folderId}/documents`
Retrieves all documents within a specific folder.
Retrieves all documents within a specific folder, including filename and labels. Returns a lighter-weight format than `GET /document/{id}` (excludes `client_id`).
**Security**: Requires JWT authentication
**Query Parameters**:
- `textRecord` (optional, default: false): When true, includes the full text extraction record for each document
**Response**:
```json
@@ -559,9 +629,13 @@ Retrieves all documents within a specific folder.
"documents": [
{
"id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
"client_id": "AAA",
"hash": "sha256:abc123...",
"fields": {}
"hasTextRecord": true,
"folderId": "019580df-ef65-7676-8de9-94435a93337a",
"filename": "contract_2024.pdf",
"originalPath": "/documents/2024/contract_2024.pdf",
"labels": [],
"fileSizeBytes": 1048576
}
]
}
@@ -661,7 +735,7 @@ Retrieves all documents that have been tagged with a specific label.
**Query Parameters**:
- `clientId` (required): Client ID to filter documents (UUID)
- `clientId` (required): Client ID to filter documents (string, max 36 chars)
**Response**:
@@ -834,106 +908,6 @@ Retrieves a specific version of a field extraction for a document by version num
---
## Query Management (QueryService)
### `GET /query`
Lists all available queries in the system.
**Security**: Requires JWT authentication
**Response** (`ListQueries`):
```json
{
"queries": [
{
"id": "019580df-ef65-7676-8de9-94435a93337a",
"type": "JSON_EXTRACTOR",
"active_version": 1,
"latest_version": 2,
"config": "{...}",
"required_queries": ["019580df-ef65-7676-8de9-94435a93337b"]
}
]
}
```
**Query Types**: `JSON_EXTRACTOR`, `CONTEXT_FULL`
### `POST /query`
Creates a new query definition.
**Security**: Requires JWT authentication
**Request Body** (`QueryCreate`):
```json
{
"type": "JSON_EXTRACTOR",
"config": "{\"key\": \"value\"}",
"required_queries": ["019580df-ef65-7676-8de9-94435a93337b"]
}
```
**Response** (`201 Created`):
```json
{
"id": "019580df-ef65-7676-8de9-94435a93337a"
}
```
### `GET /query/{id}`
Retrieves query details including configuration.
**Security**: Requires JWT authentication
**Response**: `Query` object
### `PATCH /query/{id}`
Updates query definition.
**Security**: Requires JWT authentication
**Request Body** (`QueryUpdate`):
```json
{
"config": "{\"updated\": true}",
"active_version": 2,
"required_queries": []
}
```
### `POST /query/{id}/test`
Tests query execution against a document.
**Security**: Requires JWT authentication
**Request Body** (`QueryTestRequest`):
```json
{
"document_id": "019580df-b3f8-7348-9ab1-1e55b3f18ed7",
"query_version": 1
}
```
**Response** (`QueryTestResponse`):
```json
{
"value": "extracted result"
}
```
---
## Collector Configuration (CollectorService)
### `GET /client/{id}/collector`
@@ -1624,6 +1598,16 @@ These endpoints handle authentication flows and bypass normal authorization:
| `GET /login` | Initiates OAuth2/PKCE login flow with Cognito |
| `GET /login-callback` | Handles OAuth2 callback from Cognito |
### Auth-Only Endpoints (JWT required, no Permit.io check)
The following endpoints require a valid JWT token but do **not** check Permit.io permissions. Any authenticated user can access them:
| Endpoint | Purpose |
| ------------------ | ------------------------------------------------ |
| `GET /identity` | Users need to discover their roles |
| `GET /eula/status` | Users need to check their EULA agreement status |
| `POST /eula/agree` | Users need to be able to agree to the EULA |
### Authorization Reference Table
The following table shows what data is passed to Permit.io for each protected endpoint:
@@ -1660,12 +1644,6 @@ The following table shows what data is passed to Permit.io for each protected en
| `GET` | `/field-extractions` | `field-extractions` | `get` | Get latest extraction |
| `GET` | `/field-extractions/version` | `field-extractions` | `get` | Get specific version |
| `GET` | `/field-extractions/history` | `field-extractions` | `get` | Get extraction history |
| **Query Management** |
| `GET` | `/query` | `query` | `get` | List queries |
| `POST` | `/query` | `query` | `post` | Create query |
| `GET` | `/query/{id}` | `query` | `get` | Get query details |
| `PATCH` | `/query/{id}` | `query` | `patch` | Update query |
| `POST` | `/query/{id}/test` | `query` | `post` | Test query execution |
| **Collector Configuration** |
| `GET` | `/client/{id}/collector` | `client` | `get` | Get collector config |
| `PATCH` | `/client/{id}/collector` | `client` | `patch` | Update collector config |
@@ -1683,8 +1661,8 @@ The following table shows what data is passed to Permit.io for each protected en
| `POST` | `/admin/users/{email}/enable` | `admin` | `post` | Enable user |
| **EULA Operations** |
| `GET` | `/eula` | - | - | Public (no auth) |
| `GET` | `/eula/status` | `eula` | `get` | Get user's EULA status |
| `POST` | `/eula/agree` | `eula` | `post` | Record EULA agreement |
| `GET` | `/eula/status` | - | - | Auth-only (no Permit.io)|
| `POST` | `/eula/agree` | - | - | Auth-only (no Permit.io)|
| `GET` | `/admin/eula` | `admin` | `get` | List EULA versions |
| `POST` | `/admin/eula` | `admin` | `post` | Create EULA version |
| `GET` | `/admin/eula/{version_id}` | `admin` | `get` | Get EULA version |
@@ -1708,10 +1686,8 @@ To configure Permit.io to work with this API, administrators must create:
| `folders` | Folder management |
| `labels` | Label-based document queries |
| `field-extractions` | Field extraction operations |
| `query` | Query definition management |
| `export` | Export operations |
| `admin` | User administration and EULA admin operations |
| `eula` | EULA status and agreement operations |
#### Actions
@@ -1729,8 +1705,8 @@ Typical role assignments for common personas:
| Role | Resources | Actions | Use Case |
| ------------ | -------------------------------------------------------------------------- | ---------------------- | -------------------------- |
| `viewer` | `client`, `clients`, `document`, `documents`, `folders`, `query`, `export` | `get` | Read-only access |
| `editor` | `client`, `document`, `documents`, `folders`, `field-extractions`, `query` | `get`, `post`, `patch` | Content management |
| `viewer` | `client`, `clients`, `document`, `documents`, `folders`, `export` | `get` | Read-only access |
| `editor` | `client`, `document`, `documents`, `folders`, `field-extractions` | `get`, `post`, `patch` | Content management |
| `admin` | All resources | All actions | Full administrative access |
| `user_admin` | `admin` | All actions | User management only |