{ "info": { "_postman_id": "immiblox-api-collection", "name": "Immiblox API Collection", "description": "# Immiblox API Collection\n\n**Public-facing APIs only.** This collection documents endpoints available for app builders and integrators.\n\nInternal routes (`/api/v1/internal/*`) and admin-only endpoints are excluded.\n\n## Services\n\n- **Account** - Auth, signup, signin, OAuth\n- **Vault** - Vaults, shares, public access\n- **Document** - Upload, list, search, public share upload/download\n- **Assistant** - RAG, conversations, news\n- **Workflow** - Workflows, engine, executions\n- **Immigration** - Persons, statuses, compliance\n- **Organization** - Organizations, members, machine auth (API keys)\n- **Webhook** - Webhooks, events\n- **MCP** - Chat, tools\n\n## Authentication\n\n- **JWT:** `Authorization: Bearer ` (from signin/OAuth)\n- **Machine:** `X-API-Key` + `X-App-Key` (organization integrations)\n- **Share token:** For public vault access (no auth)\n\n## Getting Started\n\n1. Import this collection and an environment file\n2. Start with Sign In to get `access_token`\n3. Use the token for vault, document, assistant, and workflow requests", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Account Service", "item": [ { "name": "Authentication", "item": [ { "name": "Sign Up", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.access_token) {", " pm.environment.set('access_token', jsonData.access_token);", " }", " if (jsonData.account && jsonData.account.id) {", " pm.environment.set('user_id', jsonData.account.id);", " }", " if (jsonData.account && jsonData.account.email) {", " pm.environment.set('test_email', jsonData.account.email);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{admin_token}}", "description": "Required in production for admin access", "disabled": true } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"{{test_email}}\",\n \"password\": \"{{test_password}}\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/auth/signup", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "signup" ] }, "description": "Create a new user account. Returns JWT access token and account information.\n\n**Important:** If you get an error that the user already exists, you can use the Sign In endpoint instead.\n\n**Note:** In production, this endpoint may require admin authorization (Authorization header)." }, "response": [] }, { "name": "Sign In", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.access_token) {", " pm.environment.set('access_token', jsonData.access_token);", " }", " if (jsonData.account && jsonData.account.id) {", " pm.environment.set('user_id', jsonData.account.id);", " }", "} else if (pm.response.code === 401) {", " console.log('Sign in failed. Make sure the user exists. Try Sign Up first if this is a new user.');", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"{{test_email}}\",\n \"password\": \"{{test_password}}\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/auth/signin", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "signin" ] }, "description": "Authenticate an existing user with email and password. Returns JWT access token and account information.\n\n**Troubleshooting:**\n- If you get \"Invalid email or password\", the user account doesn't exist yet. Use the Sign Up endpoint first to create an account.\n- Make sure the `test_email` and `test_password` environment variables are set correctly.\n- After successful sign in, the `access_token` and `user_id` will be automatically saved to your environment variables." }, "response": [] }, { "name": "Sign Out", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{account_base_url}}/api/v1/auth/signout", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "signout" ] }, "description": "Sign out the current user. Note: JWT tokens are stateless, so this is primarily for client-side cleanup." }, "response": [] }, { "name": "Forgot Password", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " console.log('Password reset email sent (if account exists)');", " console.log('Check your email for the reset link, or check server logs in development mode');", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"{{test_email}}\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/auth/forgot-password", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "forgot-password" ] }, "description": "Request a password reset. Sends an email with a reset token to the specified email address.\n\n**Note:**\n- This endpoint always returns a success message to prevent email enumeration attacks\n- If the email exists, a reset token will be sent (check your email or server logs)\n- Reset tokens expire after 1 hour\n- In development mode, if SMTP is not configured, the reset token will be logged in the server logs\n\n**Required Fields:**\n- `email`: Email address associated with the account\n\n**Response:** Always returns success message regardless of whether email exists (for security)\n\n**Error Responses:**\n- `400 Bad Request`: Invalid email format" }, "response": [] }, { "name": "Reset Password", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"reset_token\": \"{{reset_token}}\",\n \"new_password\": \"NewPassword123!\",\n \"confirm_password\": \"NewPassword123!\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/auth/reset-password", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "reset-password" ] }, "description": "Reset password using the reset token received via email.\n\n**Usage Flow:**\n1. First, use the \"Forgot Password\" endpoint to request a reset token\n2. Check your email for the reset link, or check server logs in development mode\n3. Extract the reset token from the email link or logs\n4. Use this endpoint with the token to set a new password\n\n**Required Fields:**\n- `reset_token`: Reset token from the password reset email\n- `new_password`: New password for the account\n- `confirm_password`: Confirmation of the new password (must match)\n\n**Note:**\n- Reset tokens expire after 1 hour\n- After successful reset, the token is invalidated\n- You can now sign in with the new password using the \"Sign In\" endpoint\n\n**Error Responses:**\n- `400 Bad Request`: Invalid or expired reset token, passwords don't match, or invalid password format" }, "response": [] }, { "name": "Google OAuth", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.access_token) {", " pm.environment.set('access_token', jsonData.access_token);", " }", " if (jsonData.account && jsonData.account.id) {", " pm.environment.set('user_id', jsonData.account.id);", " }", " if (jsonData.account && jsonData.account.email) {", " pm.environment.set('test_email', jsonData.account.email);", " }", " console.log('Google OAuth authentication successful');", "} else if (pm.response.code === 401) {", " console.log('Google OAuth failed. Make sure the token is valid.');", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"token\": \"{{google_id_token}}\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/auth/google", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "google" ] }, "description": "Authenticate with Google OAuth using a Google ID token.\n\n**How to Get a Google ID Token:**\n\n**Option 1: Using Google Identity Services (Recommended for Web Apps)**\n1. Use Google Identity Services JavaScript library in your frontend\n2. Call `window.google.accounts.id.initialize()` with your client ID\n3. Use `window.google.accounts.id.prompt()` or render a button\n4. Google will return an ID token in the callback\n5. Send that token to this endpoint\n\n**Option 2: Using Postman (For Testing)**\n1. You'll need to obtain a Google ID token from a web application\n2. The token is typically obtained through the Google Sign-In flow in a browser\n3. Copy the token and set it as `{{google_id_token}}` in your Postman environment\n\n**Note:** Google ID tokens are short-lived (typically 1 hour) and are specific to your Google OAuth client ID.\n\n**Request Body:**\n- `token` (required): Google ID token obtained from Google Sign-In flow\n\n**Response:**\nReturns JWT access token and account information. The `access_token` and `user_id` will be automatically saved to your environment variables.\n\n**Account Behavior:**\n- If Google ID exists \u2192 Signs in existing user\n- If email exists but no Google ID \u2192 Links Google account to existing email account\n- If neither exists \u2192 Creates new account with Google authentication\n\n**Error Responses:**\n- `401 Unauthorized`: Invalid or expired Google token, or Google account email not available\n- `400 Bad Request`: Missing or invalid token format\n\n**Security Note:**\n- Google ID tokens are verified server-side with Google's servers\n- Tokens must be obtained through the official Google Sign-In flow\n- Never share or hardcode Google ID tokens" }, "response": [] }, { "name": "Discover Auth Method", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"{{test_email}}\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/auth/discover", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "discover" ] }, "description": "Discover the recommended authentication method for an email (organization password, cognito password, or google)." }, "response": [] }, { "name": "Get Cognito Google URL", "request": { "method": "GET", "url": { "raw": "{{account_base_url}}/api/v1/auth/cognito/google-url?redirect_uri={{web_base_url}}/auth/callback", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "cognito", "google-url" ], "query": [ { "key": "redirect_uri", "value": "{{web_base_url}}/auth/callback" } ] }, "description": "Get Cognito hosted UI URL for Google sign in." }, "response": [] }, { "name": "Exchange Cognito Code", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"code\": \"{{cognito_auth_code}}\",\n \"redirect_uri\": \"{{web_base_url}}/auth/callback\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/auth/cognito/exchange", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "cognito", "exchange" ] }, "description": "Exchange Cognito authorization code for application session tokens." }, "response": [] }, { "name": "Get Cognito Logout URL", "request": { "method": "GET", "url": { "raw": "{{account_base_url}}/api/v1/auth/cognito/logout-url?logout_uri={{web_base_url}}", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "auth", "cognito", "logout-url" ], "query": [ { "key": "logout_uri", "value": "{{web_base_url}}" } ] }, "description": "Get Cognito logout URL for hosted UI sign-out." }, "response": [] } ] }, { "name": "Account Management", "item": [ { "name": "Get Current Account", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{account_base_url}}/api/v1/account/me", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "account", "me" ] }, "description": "Get current authenticated user's account information." }, "response": [] }, { "name": "Change Password", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"current_password\": \"OldPassword123!\",\n \"new_password\": \"NewPassword123!\",\n \"confirm_password\": \"NewPassword123!\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/account/change-password", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "account", "change-password" ] }, "description": "Change account password. Requires current password verification." }, "response": [] }, { "name": "Change Email", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"new_email\": \"newemail@example.com\",\n \"password\": \"SecurePassword123!\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/account/change-email", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "account", "change-email" ] }, "description": "Change account email address. Requires password verification for security." }, "response": [] }, { "name": "Change Username", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"new_username\": \"newusername\",\n \"password\": \"SecurePassword123!\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/account/change-username", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "account", "change-username" ] }, "description": "Change account username. Requires password verification for security." }, "response": [] } ] }, { "name": "Family Members", "item": [ { "name": "Create Family Member", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.id) {", " pm.environment.set('family_member_id', jsonData.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"relationship\": \"Spouse\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/family-members", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "family-members" ] }, "description": "Create a new family member for the current user.\n\n**Required Fields:**\n- `first_name`: First name of the family member\n- `last_name`: Last name of the family member\n- `relationship`: Relationship to the user (e.g., \"Spouse\", \"Child\", \"Parent\")\n\n**Response:** Returns the created family member with ID. The `family_member_id` will be automatically saved to your environment variables.\n\n**Error Responses:**\n- `401 Unauthorized`: Missing or invalid authentication token\n- `400 Bad Request`: Invalid input data" }, "response": [] }, { "name": "List Family Members", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{account_base_url}}/api/v1/family-members", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "family-members" ] }, "description": "List all family members for the current authenticated user.\n\n**Response:** Returns a list of all family members associated with the user's account.\n\n**Error Responses:**\n- `401 Unauthorized`: Missing or invalid authentication token" }, "response": [] }, { "name": "Get Family Member", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{account_base_url}}/api/v1/family-members/{{family_member_id}}", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "family-members", "{{family_member_id}}" ] }, "description": "Get a specific family member by ID.\n\n**Error Responses:**\n- `404 Not Found`: Family member not found or doesn't belong to user\n- `401 Unauthorized`: Missing or invalid authentication token\n- `400 Bad Request`: Invalid family member ID format" }, "response": [] }, { "name": "Update Family Member", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"relationship\": \"Spouse\"\n}" }, "url": { "raw": "{{account_base_url}}/api/v1/family-members/{{family_member_id}}", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "family-members", "{{family_member_id}}" ] }, "description": "Update a family member's information.\n\n**Optional Fields (all fields are optional, only include fields you want to update):**\n- `first_name`: Updated first name\n- `last_name`: Updated last name\n- `relationship`: Updated relationship\n\n**Error Responses:**\n- `404 Not Found`: Family member not found or doesn't belong to user\n- `401 Unauthorized`: Missing or invalid authentication token\n- `400 Bad Request`: Invalid family member ID format or invalid input data" }, "response": [] }, { "name": "Delete Family Member", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{account_base_url}}/api/v1/family-members/{{family_member_id}}", "host": [ "{{account_base_url}}" ], "path": [ "api", "v1", "family-members", "{{family_member_id}}" ] }, "description": "Delete a family member.\n\n**Error Responses:**\n- `404 Not Found`: Family member not found or doesn't belong to user\n- `401 Unauthorized`: Missing or invalid authentication token\n- `400 Bad Request`: Invalid family member ID format" }, "response": [] } ] }, { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{account_base_url}}/health", "host": [ "{{account_base_url}}" ], "path": [ "health" ] }, "description": "Service health check endpoint." }, "response": [] } ] }, { "name": "Vault Service", "item": [ { "name": "Create Vault", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.id) {", " pm.environment.set('vault_id', jsonData.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"family_member_id\": null,\n \"family_member_name\": null,\n \"description\": \"Personal immigration documents\"\n}" }, "url": { "raw": "{{vault_base_url}}/api/v1/vaults", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults" ] }, "description": "Create a new vault for organizing documents. After successful creation, the `vault_id` will be automatically saved to your environment variables.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID\n\n**Request Body:**\n- `family_member_id` (optional): UUID of family member to associate vault with. If `null`, vault is for the user themselves.\n- `family_member_name` (optional): Full name of family member (used for name generation if family_member_id is provided)\n- `description` (optional): Description of the vault\n\n**Note:** The vault name is automatically generated based on the family member. If `family_member_id` is `null`, the vault is for the user themselves.\n\n**Error Responses:**\n- `409 Conflict`: Vault name already exists for this account\n- `400 Bad Request`: Invalid ID format" }, "response": [] }, { "name": "List Vaults", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.vaults && jsonData.vaults.length > 0 && jsonData.vaults[0].id) {", " pm.environment.set('vault_id', jsonData.vaults[0].id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{vault_base_url}}/api/v1/vaults", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults" ] }, "description": "List all vaults for the authenticated user. The first vault's `vault_id` will be automatically saved to your environment variables.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID" }, "response": [] }, { "name": "Get Vault", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.id) {", " pm.environment.set('vault_id', jsonData.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}" ] }, "description": "Get vault details by ID. The `vault_id` will be automatically saved to your environment variables.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID\n\n**Error Responses:**\n- `404 Not Found`: Vault not found or doesn't belong to user\n- `403 Forbidden`: Access denied" }, "response": [] }, { "name": "Update Vault", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Updated Vault Name\",\n \"description\": \"Updated description\"\n}" }, "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}" ] }, "description": "Update vault information.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID\n\n**Error Responses:**\n- `409 Conflict`: Vault name already exists for this account\n- `404 Not Found`: Vault not found\n- `403 Forbidden`: Access denied" }, "response": [] }, { "name": "Delete Vault", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}" ] }, "description": "Delete a vault (soft delete - sets `is_active` to false).\n\n**Headers Required:**\n- `X-User-ID`: User's UUID\n\n**Error Responses:**\n- `404 Not Found`: Vault not found or doesn't belong to user\n- `403 Forbidden`: Access denied" }, "response": [] }, { "name": "Get Vault Activity", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}/activity?limit=50&offset=0", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "activity" ], "query": [ { "key": "limit", "value": "50", "description": "Maximum number of activities to return (1-100, default: 50)" }, { "key": "offset", "value": "0", "description": "Number of activities to skip for pagination (default: 0)" }, { "key": "action", "value": "", "description": "Optional: Filter by action type (UPLOAD, DELETE, DOWNLOAD, SHARE_CREATE, SHARE_REVOKE, PERMISSION_CHANGE, MOVE_IN, MOVE_OUT)", "disabled": true } ] }, "description": "Get activity history for a vault.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID\n\n**Query Parameters:**\n- `limit` (optional): Maximum number of activities to return (1-100, default: 50)\n- `offset` (optional): Number of activities to skip for pagination (default: 0)\n- `action` (optional): Filter by action type (UPLOAD, DELETE, DOWNLOAD, SHARE_CREATE, SHARE_REVOKE, PERMISSION_CHANGE, MOVE_IN, MOVE_OUT)\n\n**Response:**\n- `activities`: Array of activity log entries\n- `total`: Total number of matching activities\n- `has_more`: Boolean indicating if there are more activities\n\n**Error Responses:**\n- `404 Not Found`: Vault not found\n- `403 Forbidden`: Access denied" }, "response": [] }, { "name": "Vault Sharing", "item": [ { "name": "Share Vault", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.shares && jsonData.shares.length > 0) {", " var share = jsonData.shares[0];", " if (share.id) {", " pm.environment.set('share_id', share.id);", " }", " if (share.public_token) {", " pm.environment.set('share_token', share.public_token);", " console.log('Share token saved: ' + share.public_token);", " }", " if (share.public_link) {", " console.log('Public link: ' + share.public_link);", " }", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"emails\": [\"recipient@example.com\"],\n \"permission\": \"view\",\n \"can_view\": true,\n \"can_download\": false,\n \"can_upload\": false\n}" }, "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}/shares", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "shares" ] }, "description": "Share a vault with one or more users by email.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID (must be the vault owner)\n\n**Request Body:**\n- `emails` (required): List of email addresses to share with (max 50)\n- `permission` (optional, default: \"view\"): Legacy permission level - \"view\" or \"edit\"\n- `can_view` (optional): Can view vault and documents (default: true)\n- `can_download` (optional): Can download documents (default: false for view, true for edit)\n- `can_upload` (optional): Can upload/delete documents (default: false for view, true for edit)\n\n**Permission Shortcuts:**\n- `view`: Sets can_view=true, can_download=false, can_upload=false\n- `edit`: Sets can_view=true, can_download=true, can_upload=true\n\n**Note:** Granular permissions (can_view, can_download, can_upload) override the legacy permission field when provided.\n\n**Response:** Returns the created shares and any errors.\n\n**Note:** \n- Only the vault owner can share a vault\n- Sharing with an email that doesn't have an account will be recorded but the share becomes active when the user signs up\n- The `share_id` will be automatically saved to your environment variables\n\n**Error Responses:**\n- `403 Forbidden`: Only vault owner can share\n- `404 Not Found`: Vault not found\n- `400 Bad Request`: Invalid request (no emails, too many emails, invalid permission)" }, "response": [] }, { "name": "List Vault Shares", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.shares && jsonData.shares.length > 0) {", " var share = jsonData.shares[0];", " if (share.id) {", " pm.environment.set('share_id', share.id);", " }", " if (share.public_token) {", " pm.environment.set('share_token', share.public_token);", " console.log('Share token saved: ' + share.public_token);", " }", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}/shares", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "shares" ] }, "description": "List all shares for a vault. Only the vault owner can view shares.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID (must be the vault owner)\n\n**Response:** Returns a list of all shares for the vault, including:\n- Share ID\n- Recipient email\n- Permission level (view/edit)\n- Share status\n- Created/updated timestamps\n\n**Note:** The first share's `share_id` will be automatically saved to your environment variables.\n\n**Error Responses:**\n- `403 Forbidden`: Only vault owner can view shares\n- `404 Not Found`: Vault not found" }, "response": [] }, { "name": "Update Share Permission", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"permission\": \"edit\",\n \"can_view\": true,\n \"can_download\": true,\n \"can_upload\": true\n}" }, "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}/shares/{{share_id}}", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "shares", "{{share_id}}" ] }, "description": "Update the permission level of a vault share. Only the vault owner can update permissions.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID (must be the vault owner)\n\n**Request Body:**\n- `permission` (optional): Legacy permission level - \"view\" or \"edit\"\n- `can_view` (optional): Can view vault and documents\n- `can_download` (optional): Can download documents\n- `can_upload` (optional): Can upload/delete documents\n\n**Note:** You can update just the legacy permission field, just the granular permissions, or both. Granular permissions take precedence when evaluating access.\n\n**Response:** Returns the updated share object.\n\n**Error Responses:**\n- `403 Forbidden`: Only vault owner can update share permissions\n- `404 Not Found`: Share or vault not found\n- `400 Bad Request`: Invalid permission value" }, "response": [] }, { "name": "Remove Share", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{vault_base_url}}/api/v1/vaults/{{vault_id}}/shares/{{share_id}}", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "shares", "{{share_id}}" ] }, "description": "Remove a vault share. Both the vault owner and the share recipient can remove a share.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID (must be vault owner OR share recipient)\n\n**Permissions:**\n- Vault owner can remove any share\n- Share recipient can remove their own share (leave the vault)\n\n**Response:** Success message confirming share removal.\n\n**Error Responses:**\n- `403 Forbidden`: Not authorized to remove this share\n- `404 Not Found`: Share or vault not found" }, "response": [] }, { "name": "Get Vaults Shared With Me", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{vault_base_url}}/api/v1/vaults/shared-with-me", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "vaults", "shared-with-me" ] }, "description": "Get all vaults that have been shared with the current user by other users.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID\n\n**Response:** Returns a list of vaults shared with the user, including:\n- Vault details (id, name, description)\n- Permission level (view/edit)\n- Owner information\n- Share creation date\n\n**Note:** This is separate from the user's own vaults (returned by \"List Vaults\"). To get a complete list of accessible vaults, call both endpoints.\n\n**Error Responses:**\n- `400 Bad Request`: Invalid user ID format" }, "response": [] } ] }, { "name": "Public Access", "item": [ { "name": "Validate Share Token", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.valid && jsonData.vault_id) {", " pm.environment.set('shared_vault_id', jsonData.vault_id);", " console.log('Token is valid for vault: ' + jsonData.vault_name);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{vault_base_url}}/api/v1/public/validate-token/{{share_token}}", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "public", "validate-token", "{{share_token}}" ] }, "description": "Validate a share token without returning full vault details.\n\nUseful for frontend to check if a token is valid before showing the full page.\n\n**Path Parameters:**\n- `share_token`: The public share token from the invitation email\n\n**Response:**\n- `valid`: Boolean indicating if token is valid\n- `vault_name`: Name of the shared vault (if valid)\n- `vault_id`: ID of the vault (if valid)\n- `shared_with_email`: Email the vault was shared with\n- `is_pending`: Whether the recipient has an account yet\n- `permissions`: Object with can_view, can_download, can_upload flags\n\n**Note:** This endpoint does not require authentication." }, "response": [] }, { "name": "Get Shared Vault by Token", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.vault && jsonData.vault.id) {", " pm.environment.set('shared_vault_id', jsonData.vault.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{vault_base_url}}/api/v1/public/shared/{{share_token}}", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "public", "shared", "{{share_token}}" ] }, "description": "Access a shared vault using a public token.\n\nThis endpoint allows view-only access to a vault without requiring authentication. The token is included in share invitation emails.\n\n**Path Parameters:**\n- `share_token`: The public share token from the invitation email\n\n**Response:**\n- `vault`: Vault details (id, name, description, created_at)\n- `share`: Share details (id, permission, shared_with_email, is_pending)\n- `permissions`: Object with can_view, can_download, can_upload flags\n- `access_type`: \"public_link\"\n- `message`: Informational message about access type\n\n**Error Responses:**\n- `404 Not Found`: Invalid or expired share link, or vault deleted\n- `500 Internal Server Error`: Failed to access shared vault\n\n**Note:** This endpoint does not require authentication." }, "response": [] }, { "name": "List Shared Vault Documents", "request": { "method": "GET", "header": [], "url": { "raw": "{{vault_base_url}}/api/v1/public/shared/{{share_token}}/documents", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "public", "shared", "{{share_token}}", "documents" ] }, "description": "List documents in a shared vault using a public token.\n\nThis endpoint allows view-only access to vault documents without requiring authentication. Returns document metadata for display.\n\n**Path Parameters:**\n- `share_token`: The public share token from the invitation email\n\n**Response:**\n- `vault_id`: UUID of the vault\n- `vault_name`: Name of the vault\n- `documents`: Array of document objects with metadata\n - `id`: Document UUID\n - `file_name`: Original file name\n - `file_size`: File size in bytes\n - `mime_type`: MIME type of the file\n - `document_type`: Type of document\n - `category`: Document category\n - `ocr_status`: OCR processing status\n - `upload_date`: When the document was uploaded\n- `total_documents`: Total number of documents\n- `permissions`: Object with can_view, can_download, can_upload flags\n\n**Error Responses:**\n- `404 Not Found`: Invalid or expired share link, or vault deleted\n- `500 Internal Server Error`: Failed to list documents\n\n**Note:** This endpoint does not require authentication." }, "response": [] }, { "name": "Get Document Download URL (Public)", "request": { "method": "GET", "header": [], "url": { "raw": "{{vault_base_url}}/api/v1/public/shared/{{share_token}}/documents/{{document_id}}/download-url", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "public", "shared", "{{share_token}}", "documents", "{{document_id}}", "download-url" ] }, "description": "Get a download URL for a document in a shared vault.\n\nThis endpoint validates the share token and checks can_download permission. Returns the document service URL for downloading the document.\n\n**Path Parameters:**\n- `share_token`: The public share token from the invitation email\n- `document_id`: UUID of the document to download\n\n**Response:**\n- `document_id`: UUID of the document\n- `file_name`: Original file name\n- `vault_id`: UUID of the vault\n- `download_allowed`: Boolean indicating if download is permitted\n- `message`: Instructions for downloading\n\n**Error Responses:**\n- `403 Forbidden`: No download permission on this vault\n- `404 Not Found`: Invalid share link, vault deleted, or document not found\n- `400 Bad Request`: Invalid document ID\n- `500 Internal Server Error`: Failed to get download URL\n\n**Note:** This endpoint does not require authentication, but the share must have can_download permission." }, "response": [] }, { "name": "Upload Document (Public Share)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"uploader_name\": \"John Doe\",\n \"uploader_email\": \"john@example.com\"\n}" }, "url": { "raw": "{{vault_base_url}}/api/v1/public/shared/{{share_token}}/documents/upload", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "public", "shared", "{{share_token}}", "documents", "upload" ] }, "description": "Validate upload permissions for a shared vault via public link.\n\nThis endpoint checks if the share token has upload permission. The actual file upload is handled by the document service public upload endpoint.\n\n**Path Parameters:**\n- `share_token`: The public share token from the invitation email\n\n**Optional Body Fields:**\n- `uploader_name`: Name of the person uploading (for attribution)\n- `uploader_email`: Email of the person uploading (for attribution)\n\n**Response:**\n- `upload_allowed`: Boolean indicating if upload is permitted\n- `vault_id`: UUID of the vault to upload to\n- `vault_name`: Name of the vault\n- `share_token`: The share token (for use with document service)\n- `uploader_info`: Object with uploader name and email\n- `message`: Instructions for uploading\n\n**Error Responses:**\n- `403 Forbidden`: No upload permission on this vault\n- `404 Not Found`: Invalid share link or vault deleted\n- `500 Internal Server Error`: Failed to validate upload permissions\n\n**Note:** This endpoint does not require authentication, but the share must have can_upload permission. After calling this endpoint, use the Document Service public upload endpoint to actually upload the file." }, "response": [] }, { "name": "Create Share Session", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200 || pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.session_token) {", " pm.environment.set('share_session_token', jsonData.session_token);", " console.log('Share session created, expires: ' + jsonData.expires_at);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"token\": \"{{share_token}}\"\n}" }, "url": { "raw": "{{vault_base_url}}/api/v1/public/session/create", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "public", "session", "create" ] }, "description": "Create a session for continued public share access.\n\nWhen a user clicks a share link, the frontend should call this endpoint to get a session token. The session is valid for 24 hours.\n\n**Session-based Access Flow:**\n1. User clicks share link with token (valid for 7 days)\n2. Frontend calls /session/create with token \u2192 gets session_token (valid 24 hours)\n3. Frontend stores session_token in localStorage\n4. Subsequent requests include X-Share-Session header\n5. If session expires, user clicks link again\n6. If link expires, auto-resend email with new link\n\n**Body:**\n- `token`: The public share link token\n\n**Response:**\n- `session_token`: Token to include in X-Share-Session header for subsequent requests\n- `expires_at`: When the session expires (ISO format)\n- `share_id`: UUID of the share\n- `vault_id`: UUID of the vault\n\n**Error Responses:**\n- `400 Bad Request`: Token is required\n- `404 Not Found`: Invalid share link\n- `410 Gone`: Share link has expired (new email sent)\n- `500 Internal Server Error`: Failed to create session\n\n**Note:** This endpoint does not require authentication." }, "response": [] }, { "name": "Validate Share Session", "request": { "method": "GET", "header": [ { "key": "X-Share-Session", "value": "{{share_session_token}}", "description": "The session token to validate" } ], "url": { "raw": "{{vault_base_url}}/api/v1/public/session/validate", "host": [ "{{vault_base_url}}" ], "path": [ "api", "v1", "public", "session", "validate" ] }, "description": "Validate an existing share session.\n\n**Headers:**\n- `X-Share-Session`: The session token to validate (required)\n\n**Response:**\n- `valid`: Boolean - whether the session is still valid\n- `expires_at`: When the session expires (if valid)\n- `share_id`: UUID of the share (if valid)\n- `vault_id`: UUID of the vault being accessed (if valid)\n- `permissions`: Object with can_view, can_download, can_upload flags\n- `reason`: Reason for invalidity if not valid (session_expired_or_invalid, share_revoked, error)\n\n**Note:** This endpoint does not require authentication." }, "response": [] } ] }, { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{vault_base_url}}/health", "host": [ "{{vault_base_url}}" ], "path": [ "health" ] }, "description": "Service health check endpoint." }, "response": [] } ] }, { "name": "Document Service", "item": [ { "name": "Documents", "item": [ { "name": "Upload Document", "request": { "method": "POST", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "file", "type": "file", "src": [], "description": "Document file (PDF, image, etc.)" }, { "key": "document_type_id", "value": "{{document_type_id}}", "type": "text", "description": "UUID of document type (optional - will auto-detect from OCR if not provided)", "disabled": true }, { "key": "person_name", "value": "", "type": "text", "description": "Name of person on document (optional - will be extracted via OCR if needed)", "disabled": true }, { "key": "document_type", "value": "", "type": "text", "description": "Type of document (optional - kept for backward compatibility)", "disabled": true }, { "key": "institution_name", "value": "", "type": "text", "description": "Institution that issued the document (optional)", "disabled": true } ] }, "url": { "raw": "{{document_base_url}}/api/v1/vaults/{{vault_id}}/documents/upload", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "documents", "upload" ] }, "description": "Upload a document to a vault. OCR processing will begin automatically in the background, and document type will be auto-detected from the OCR text.\n\n**Required Fields:**\n- `file`: Document file (PDF, image, etc.)\n\n**Optional Fields:**\n- `document_type_id`: UUID of document type (if not provided, will auto-detect from OCR and default to \"OTHER\" if detection fails)\n- `person_name`: Name of person on document (will be extracted via OCR if not provided)\n- `document_type`: Type of document (kept for backward compatibility, not used if document_type_id is provided)\n- `institution_name`: Institution that issued the document\n\n**Auto-Detection:**\n- Document type is automatically determined from OCR text after upload\n- If detection fails or confidence is too low, document is assigned to \"OTHER\" type\n- Supported document types: I-94, Passport, Driver's License, Green Card, Visa, I-797, EAD, I-20, DS-2019, and more\n\n**Error Responses:**\n- `404 Not Found`: Vault not found\n- `400 Bad Request`: Invalid file or missing required fields\n- `429 Too Many Requests`: Too many concurrent uploads" }, "response": [] }, { "name": "Upload Documents (Batch)", "request": { "method": "POST", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "files", "type": "file", "src": [], "description": "Multiple document files (up to 10 files). Select multiple files in Postman." }, { "key": "document_type_id", "value": "{{document_type_id}}", "type": "text", "description": "UUID of document type (optional - will auto-detect from OCR if not provided)", "disabled": true }, { "key": "institution_name", "value": "", "type": "text", "description": "Institution that issued the documents (optional, applies to all files)", "disabled": true } ] }, "url": { "raw": "{{document_base_url}}/api/v1/vaults/{{vault_id}}/documents/upload-batch", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "documents", "upload-batch" ] }, "description": "Upload multiple documents (up to 10) to a vault in a single request. OCR processing will begin automatically in the background for each document, and document types will be auto-detected from OCR text.\n\n**Required Fields:**\n- `files`: Multiple document files (select multiple files in Postman - up to 10 files per batch)\n\n**Optional Fields:**\n- `document_type_id`: UUID of document type (if not provided, will auto-detect from OCR and default to \"OTHER\" if detection fails)\n- `institution_name`: Institution that issued the documents (applies to all files in the batch)\n\n**Batch Processing:**\n- Maximum 10 documents per batch\n- Each document is processed independently\n- Duplicate detection is performed for each file\n- Returns results for each file including success/failure status\n\n**Response Format:**\n```json\n{\n \"success\": true,\n \"total_files\": 3,\n \"successful\": 2,\n \"failed\": 1,\n \"results\": [...],\n \"errors\": [...]\n}\n```\n\n**Auto-Detection:**\n- Document types are automatically determined from OCR text after upload\n- If detection fails or confidence is too low, documents are assigned to \"OTHER\" type\n\n**Error Responses:**\n- `400 Bad Request`: Invalid files, too many files (>10), or missing required fields\n- `404 Not Found`: Vault not found" }, "response": [] }, { "name": "List Documents", "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/vaults/{{vault_id}}/documents", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "documents" ], "query": [ { "key": "search", "value": "", "description": "Optional: Search documents by OCR text content (case-insensitive)", "disabled": true } ] }, "description": "List all documents in a vault. Optionally search by content if 'search' parameter is provided.\n\n**Query Parameters:**\n- `search` (optional): Search documents by OCR text content (case-insensitive full-text search)\n\n**Examples:**\n- List all documents: `GET /api/v1/vaults/{vault_id}/documents`\n- Search documents: `GET /api/v1/vaults/{vault_id}/documents?search=passport`\n\n**Response:** Returns a list of documents with their metadata, OCR status, and file information." }, "response": [] }, { "name": "Get Document", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.document && jsonData.document.id) {", " pm.environment.set('document_id', jsonData.document.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/documents/{{document_id}}", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "{{document_id}}" ] }, "description": "Get a document by ID.\n\n**Error Responses:**\n- `404 Not Found`: Document not found\n- `400 Bad Request`: Invalid document ID format" }, "response": [] }, { "name": "Download Document", "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/documents/{{document_id}}/download", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "{{document_id}}", "download" ] }, "description": "Download a document file. Returns the file as a binary download.\n\n**Response:** Returns the document file with appropriate content-type headers.\n\n**Error Responses:**\n- `404 Not Found`: Document not found or file not found on storage\n- `400 Bad Request`: Invalid document ID format\n- `500 Internal Server Error`: File read error" }, "response": [] }, { "name": "Delete Document", "request": { "method": "DELETE", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/documents/{{document_id}}", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "{{document_id}}" ] }, "description": "Delete a document (soft delete - sets `is_active` to false).\n\n**Error Responses:**\n- `404 Not Found`: Document not found\n- `400 Bad Request`: Invalid document ID format" }, "response": [] }, { "name": "Reprocess Document", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " console.log('Document reprocessing:', jsonData.success ? 'Started' : 'Failed');", " if (jsonData.document) {", " console.log('Document type:', jsonData.document.document_type_name || 'Auto-detecting...');", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/documents/{{document_id}}/reprocess", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "{{document_id}}", "reprocess" ] }, "description": "Trigger reprocessing of a document.\n\nThis will re-run:\n- OCR text extraction\n- AI-powered document classification\n- Metadata extraction (dates, names, numbers)\n- Vector embedding generation\n\n**Use Cases:**\n- Document was uploaded before OCR improvements\n- Classification was incorrect and needs to be re-evaluated\n- Embeddings need to be regenerated\n- Metadata extraction missed important fields\n\n**Response:**\n- `success`: Whether reprocessing was triggered\n- `document`: Updated document metadata\n- `message`: Status message\n\n**Note:** Reprocessing is asynchronous. The document status will change to 'processing' and update when complete." }, "response": [] }, { "name": "Move Document", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"target_vault_id\": \"{{target_vault_id}}\"\n}" }, "url": { "raw": "{{document_base_url}}/api/v1/documents/{{document_id}}/move", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "{{document_id}}", "move" ] }, "description": "Move a document to a different vault.\n\n**Headers Required:**\n- `X-User-ID`: User's UUID\n\n**Request Body:**\n- `target_vault_id`: UUID of the destination vault\n\n**Requirements:**\n- User must have edit access to both source and target vaults\n- Document must exist and be active\n- Target vault must exist and be active\n\n**Response:**\n- `success`: Whether the move was successful\n- `document`: Updated document with new vault_id\n- `message`: Status message\n\n**Activity Logging:**\n- Logs MOVE_OUT in source vault\n- Logs MOVE_IN in target vault\n\n**Error Responses:**\n- `404 Not Found`: Document or target vault not found\n- `403 Forbidden`: Insufficient permissions\n- `400 Bad Request`: Invalid ID format or same vault" }, "response": [] }, { "name": "View Document (Inline)", "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/documents/{{document_id}}/view", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "{{document_id}}", "view" ] }, "description": "View a document inline (opens in browser rather than downloading).\n\nUnlike the `/download` endpoint which triggers a file download, this endpoint returns the document with `Content-Disposition: inline` header, causing most browsers to display the document directly.\n\n**Use Cases:**\n- PDF preview in browser\n- Image viewing without download\n- Document preview in iframe/embed\n\n**Supported Formats:**\n- PDF files (displayed in browser PDF viewer)\n- Images (JPEG, PNG, GIF, WebP)\n- Text files\n\n**Note:** The browser's ability to display the document depends on its support for the file type." }, "response": [] }, { "name": "Query Documents by Metadata", "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/vaults/{{vault_id}}/documents/metadata?field=expiration_date&value=", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "documents", "metadata" ], "query": [ { "key": "field", "value": "expiration_date", "description": "Metadata field to query (e.g., expiration_date, issue_date, issued_state, document_number)", "disabled": false }, { "key": "value", "value": "", "description": "Optional: Specific value to filter by (e.g., 'California' for issued_state)", "disabled": false } ] }, "description": "Query documents within a vault based on extracted metadata fields.\n\n**Use Cases:**\n- Find documents with expiration dates: `?field=expiration_date`\n- Find documents issued in a specific state: `?field=issued_state&value=California`\n- Find documents by document number: `?field=document_number`\n- Find documents by issue date: `?field=issue_date`\n\n**Available Metadata Fields:**\n- `expiration_date`: ISO date string (extracted from OCR text)\n- `issue_date`: ISO date string (extracted from OCR text)\n- `issued_state`: Full state name (e.g., \"California\")\n- `issued_state_abbreviation`: State abbreviation (e.g., \"CA\")\n- `document_number`: Document number (passport, license, etc.)\n- `document_number_type`: Type of document number (passport, license, etc.)\n\n**Query Parameters:**\n- `field` (required): Metadata field to query\n- `value` (optional): Specific value to filter by\n\n**Examples:**\n- Get all documents with expiration dates: `?field=expiration_date`\n- Get documents issued in California: `?field=issued_state&value=California`\n- Get documents with passport numbers: `?field=document_number`\n\n**Note:** Metadata is automatically extracted during OCR processing. If no metadata is found, this endpoint will return an empty result.\n\n**Error Responses:**\n- `404 Not Found`: No documents found matching criteria or vault not found\n- `400 Bad Request`: Invalid UUID format" }, "response": [] }, { "name": "Prefilter Documents by Type", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"document_types\": [\"PASSPORT\", \"I20\", \"EAD\"],\n \"include_pattern_matches\": true\n}" }, "url": { "raw": "{{document_base_url}}/api/v1/vaults/{{vault_id}}/documents/prefilter", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "documents", "prefilter" ] }, "description": "Fast pre-filter documents by type codes before LLM processing.\n\nThis endpoint provides a fast database-level search to find documents by their classified types, reducing the need for expensive LLM searches.\n\n**Request Body:**\n- `document_types` (required): List of document type codes to search for (e.g., [\"PASSPORT\", \"I20\", \"EAD\"])\n- `include_pattern_matches` (optional, default: true): Also search by filename patterns\n\n**Response:**\n- `prefilter_result`:\n - `by_type`: Documents matched by type classification\n - `by_pattern`: Additional matches by filename (if enabled)\n - `all`: Combined unique list\n - `summary`: Quick lookup by type (e.g., {\"PASSPORT\": [\"doc-id-1\"]})\n - `total_count`: Total number of matching documents\n\n**Use Cases:**\n- Quickly find documents by type before AI processing\n- Reduce LLM token costs by pre-filtering\n- Build document selection UIs" }, "response": [] }, { "name": "Classify Document", "request": { "method": "PATCH", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{document_base_url}}/api/v1/documents/{{document_id}}/classify?document_type_id={{document_type_id}}", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "{{document_id}}", "classify" ], "query": [ { "key": "document_type_id", "value": "{{document_type_id}}", "description": "UUID of the document type to classify as" } ] }, "description": "Manually update a document's classification.\n\nUse this endpoint to correct misclassified documents.\n\n**Query Parameters:**\n- `document_type_id` (required): The UUID of the document type to classify as\n\n**Response:**\n- `message`: Success message\n- `document`: Updated document object\n\n**Error Responses:**\n- `404 Not Found`: Document or document type not found\n- `403 Forbidden`: No edit permission on the document's vault\n- `400 Bad Request`: Invalid document type ID format" }, "response": [] }, { "name": "Forward Documents", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\",\n \"document_ids\": [\"{{document_id}}\"],\n \"recipient_emails\": [\"attorney@example.com\"],\n \"message\": \"Forwarding document for legal review\",\n \"sender_name\": \"Immigration Applicant\"\n}" }, "url": { "raw": "{{document_base_url}}/api/v1/documents/forward", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "forward" ] }, "description": "Forward documents to recipients via email. Requires vault_id, document_ids array, and recipient_emails array." }, "response": [] } ] }, { "name": "Document Types", "item": [ { "name": "List Document Types", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.document_types && jsonData.document_types.length > 0) {", " // Try to find a specific document type by code (e.g., PASSPORT, GREEN_CARD, I20, etc.)", " // You can modify the searchCode variable to find a specific type", " var searchCode = pm.environment.get('document_type_code') || 'PASSPORT';", " var foundType = jsonData.document_types.find(function(dt) {", " return dt.code === searchCode;", " });", " ", " if (foundType && foundType.id) {", " pm.environment.set('document_type_id', foundType.id);", " console.log('Found document type: ' + foundType.code + ' (ID: ' + foundType.id + ')');", " } else if (jsonData.document_types[0].id) {", " // Fallback to first document type", " pm.environment.set('document_type_id', jsonData.document_types[0].id);", " console.log('Using first document type: ' + jsonData.document_types[0].code + ' (ID: ' + jsonData.document_types[0].id + ')');", " console.log('Available document types:', jsonData.document_types.map(function(dt) { return dt.code; }).join(', '));", " }", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/document-types", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "document-types" ] }, "description": "**RECOMMENDED: Start here!** List all available document types. The system comes pre-seeded with common US immigration document types.\n\n**Pre-seeded Document Types Include:**\n- Identity: PASSPORT, DRIVERS_LICENSE, BIRTH_CERTIFICATE, MARRIAGE_CERTIFICATE, SOCIAL_SECURITY_CARD\n- Immigration Status: GREEN_CARD, VISA, I94, I797, EAD\n- Student: I20, DS2019, ACADEMIC_TRANSCRIPT, DIPLOMA\n- Employment: EMPLOYMENT_LETTER, PAY_STUB\n- Tax: W2, 1099, TAX_RETURN\n- Financial: BANK_STATEMENT, FINANCIAL_AFFIDAVIT\n- Residence: LEASE_AGREEMENT, UTILITY_BILL, MORTGAGE_STATEMENT\n- Medical: MEDICAL_EXAM, VACCINATION_RECORD\n- Legal: POLICE_CLEARANCE, APOSTILLE, TRANSLATION\n\n**Auto-selection:** The script will look for a document type code in the `document_type_code` environment variable (default: PASSPORT). If found, that type's ID will be saved to `document_type_id`. Otherwise, the first type's ID is saved.\n\nTo use a specific document type, set `document_type_code` to the desired code (e.g., \"GREEN_CARD\", \"I20\") before running this request." }, "response": [] }, { "name": "Create Document Type", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.document_type && jsonData.document_type.id) {", " pm.environment.set('document_type_id', jsonData.document_type.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"code\": \"CUSTOM_TYPE\",\n \"name\": \"Custom Document Type\",\n \"category\": \"custom\",\n \"description\": \"Custom document type description\"\n}" }, "url": { "raw": "{{document_base_url}}/api/v1/document-types", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "document-types" ] }, "description": "**OPTIONAL:** Create a custom document type. Most document types are already pre-seeded in the system. Use \"List Document Types\" first to see what's available.\n\nOnly create a new document type if you need something that's not in the pre-seeded list.\n\nAfter successful creation, the `document_type_id` will be automatically saved to your environment variables.\n\n**Required Fields:**\n- `code`: Unique code for the document type (e.g., \"CUSTOM_TYPE\")\n- `name`: Display name for the document type\n\n**Optional Fields:**\n- `category`: Category of the document (e.g., \"identity\", \"immigration_status\", \"employment\")\n- `description`: Description of the document type\n\n**Error Responses:**\n- `400 Bad Request`: Document type with code already exists" }, "response": [] }, { "name": "Get Document Type", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.document_type && jsonData.document_type.id) {", " pm.environment.set('document_type_id', jsonData.document_type.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/document-types/{{document_type_id}}", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "document-types", "{{document_type_id}}" ] }, "description": "Get document type details by ID. Useful when you know the specific document type ID you want to use.\n\nThe `document_type_id` will be automatically saved to your environment variables.\n\n**Tip:** Use \"List Document Types\" first to find the ID of the document type you need.\n\n**Error Responses:**\n- `404 Not Found`: Document type not found\n- `400 Bad Request`: Invalid document type ID format" }, "response": [] } ] }, { "name": "Document Index", "description": "Document index provides detailed information about all supported document types, including required fields, sample templates, and processing capabilities. This is useful for understanding what documents the system can process and what metadata will be extracted.", "item": [ { "name": "List All Document Types (Index)", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.success && jsonData.document_types) {", " console.log('Found ' + jsonData.document_types.length + ' document types');", " jsonData.document_types.slice(0, 5).forEach(function(dt) {", " console.log('- ' + dt.code + ': ' + dt.name);", " });", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/document-index", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "document-index" ] }, "description": "Get a comprehensive index of all supported document types with detailed information.\n\n**Returns for each document type:**\n- `code`: Internal identifier (e.g., 'PASSPORT', 'I140')\n- `name`: Human-readable name\n- `category`: Document category (identity, immigration, employment, etc.)\n- `description`: Detailed description of the document\n- `aliases`: Alternative names the AI recognizes\n- `required_fields`: Fields that should be present\n- `optional_fields`: Additional fields that may be extracted\n- `validity_period`: Typical document validity information\n- `issuing_authority`: Who issues this document\n- `sample_documents`: Example document descriptions\n\n**Use Cases:**\n- Understanding what documents the system supports\n- Getting field requirements for document types\n- Building document upload guides for users\n- AI training and classification reference" }, "response": [] }, { "name": "Get Document Type Details (Index)", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.success && jsonData.document_type) {", " var dt = jsonData.document_type;", " console.log('Document Type: ' + dt.name);", " console.log('Category: ' + dt.category);", " if (dt.required_fields) {", " console.log('Required fields: ' + dt.required_fields.join(', '));", " }", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/document-index/PASSPORT", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "document-index", "PASSPORT" ] }, "description": "Get detailed information about a specific document type by its code.\n\n**Path Parameters:**\n- `code`: Document type code (e.g., 'PASSPORT', 'I140', 'DRIVERS_LICENSE', 'GREEN_CARD')\n\n**Common Document Type Codes:**\n- Identity: `PASSPORT`, `DRIVERS_LICENSE`, `STATE_ID`, `BIRTH_CERTIFICATE`\n- Immigration: `GREEN_CARD`, `VISA`, `I94`, `EAD`, `I20`, `I797`, `I140`\n- Employment: `W2`, `PAY_STUB`, `OFFER_LETTER`, `I9`\n- Financial: `TAX_RETURN`, `BANK_STATEMENT`\n\n**Response includes:**\n- Full document type details\n- Required and optional fields\n- Validity period information\n- Issuing authority\n- Processing tips\n\n**Error Responses:**\n- `404 Not Found`: Document type code not recognized" }, "response": [] } ] }, { "name": "Public Documents", "item": [ { "name": "Upload Document (Public Share)", "request": { "method": "POST", "header": [], "body": { "mode": "formdata", "formdata": [ { "key": "share_token", "value": "{{share_token}}", "type": "text", "description": "Public share token for authentication (required)" }, { "key": "file", "type": "file", "src": [], "description": "Document file to upload (required)" }, { "key": "uploader_name", "value": "", "type": "text", "description": "Name of the person uploading (optional, for attribution)", "disabled": true }, { "key": "uploader_email", "value": "", "type": "text", "description": "Email of the person uploading (optional, for attribution)", "disabled": true }, { "key": "document_type_id", "value": "{{document_type_id}}", "type": "text", "description": "UUID of document type (optional - will auto-detect from OCR)", "disabled": true }, { "key": "institution_name", "value": "", "type": "text", "description": "Institution that issued the document (optional)", "disabled": true } ] }, "url": { "raw": "{{document_base_url}}/api/v1/public/vaults/{{vault_id}}/documents/upload", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "public", "vaults", "{{vault_id}}", "documents", "upload" ] }, "description": "Upload a document to a vault via a public share link.\n\nThis endpoint allows document uploads without user authentication, using a share token that has can_upload permission. The uploader can optionally provide their name and email for attribution.\n\n**Required Fields:**\n- `share_token`: Public share token for authentication\n- `file`: Document file to upload (PDF, image, etc.)\n\n**Optional Fields:**\n- `uploader_name`: Name of the person uploading (for attribution)\n- `uploader_email`: Email of the person uploading (for attribution)\n- `document_type_id`: UUID of document type (if not provided, will auto-detect from OCR)\n- `institution_name`: Institution that issued the document\n\n**Response:**\n- `success`: Boolean indicating upload success\n- `document`: Document object with metadata\n- `uploaded_by`: Object with uploader name and email\n- `message`: Success message\n\n**Error Responses:**\n- `403 Forbidden`: No upload permission on this vault, or token doesn't match vault\n- `404 Not Found`: Invalid or expired share token\n- `400 Bad Request`: No file content received\n- `500 Internal Server Error`: Failed to upload document\n\n**Note:** This endpoint does not require user authentication. The share token must have can_upload permission." }, "response": [] }, { "name": "Download Document (Public Share)", "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/api/v1/public/documents/{{document_id}}/download?share_token={{share_token}}", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "public", "documents", "{{document_id}}", "download" ], "query": [ { "key": "share_token", "value": "{{share_token}}", "description": "Public share token for authentication (required)" } ] }, "description": "Download a document via a public share link.\n\nThis endpoint allows document downloads without user authentication, using a share token that has can_download permission.\n\nPermission is checked fresh from the database for real-time enforcement. If the owner disables download permission, it takes effect immediately.\n\n**Path Parameters:**\n- `document_id`: UUID of the document to download\n\n**Query Parameters:**\n- `share_token`: Public share token for authentication (required)\n\n**Response:** Returns the document file as a binary download with appropriate content-type headers.\n\n**Error Responses:**\n- `403 Forbidden`: No download permission, or document not in shared vault\n- `404 Not Found`: Invalid share token, document not found, or file not found on storage\n- `400 Bad Request`: Invalid document ID format\n- `500 Internal Server Error`: Error downloading document\n\n**Note:** This endpoint does not require user authentication. The share token must have can_download permission, and the document must belong to the vault associated with the share." }, "response": [] } ] }, { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{document_base_url}}/health", "host": [ "{{document_base_url}}" ], "path": [ "health" ] }, "description": "Service health check endpoint." }, "response": [] } ] }, { "name": "Embedding Service (Document Service)", "item": [ { "name": "Semantic Search", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"query\": \"When does my passport expire?\",\n \"top_k\": 5,\n \"similarity_threshold\": 0.5,\n \"document_ids\": []\n}" }, "url": { "raw": "{{embedding_base_url}}/api/v1/vaults/{{vault_id}}/semantic-search", "host": [ "{{embedding_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "semantic-search" ] }, "description": "Perform semantic search on documents in a vault using vector embeddings.\n\n**Required Fields:**\n- `query`: Search query text\n\n**Optional Fields:**\n- `top_k`: Number of results to return (default: 5, range: 1-50)\n- `similarity_threshold`: Minimum similarity score (default: 0.5, range: 0.0-1.0)\n- `document_ids`: Array of document UUIDs to restrict search to (optional)\n - If provided, only search within the specified documents\n - If omitted or empty array, search all documents in the vault\n - Example: `[\"uuid1\", \"uuid2\", \"uuid3\"]`\n\n**Response:** Returns matching document chunks with similarity scores." }, "response": [] }, { "name": "Get Embedding Stats", "request": { "method": "GET", "header": [], "url": { "raw": "{{embedding_base_url}}/api/v1/vaults/{{vault_id}}/embedding-stats", "host": [ "{{embedding_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "embedding-stats" ] }, "description": "Get embedding statistics for a vault.\n\n**Returns:**\n- Total number of embeddings\n- Total number of documents\n- Total number of characters processed\n\n**Error Responses:**\n- `404 Not Found`: No embeddings found for vault" }, "response": [] }, { "name": "Process Existing Documents", "request": { "method": "POST", "header": [], "url": { "raw": "{{embedding_base_url}}/api/v1/vaults/{{vault_id}}/process-existing-documents", "host": [ "{{embedding_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "process-existing-documents" ] }, "description": "Manually process existing documents that have OCR text but no embeddings. This endpoint will find all documents in the vault with successful OCR but missing embeddings, and generate embeddings for them.\n\n**Use Cases:**\n- Documents were uploaded before embedding service was enabled\n- Embedding generation failed for some documents\n- Need to regenerate embeddings after changes\n\n**Response:** Returns processing statistics including:\n- Total documents found\n- Documents successfully processed\n- Documents that failed to process\n- Error messages for failed documents\n\n**Note:** This is a synchronous operation that may take time for large vaults. Documents that already have embeddings will be skipped.\n\n**Error Responses:**\n- `500 Internal Server Error`: Processing error" }, "response": [] }, { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{embedding_base_url}}/health", "host": [ "{{embedding_base_url}}" ], "path": [ "health" ] }, "description": "Service health check endpoint." }, "response": [] } ] }, { "name": "Assistant Service", "item": [ { "name": "Improve Query", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.improved_query) {", " console.log('Improved query: ' + jsonData.improved_query);", " }", " if (jsonData.search_terms && jsonData.search_terms.length > 0) {", " console.log('Search terms: ' + jsonData.search_terms.join(', '));", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"query\": \"When does my passport expire?\",\n \"conversation_id\": null\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/improve-query", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "improve-query" ] }, "description": "Improve a user query for better search results. Returns the improved query without answering it.\n\n**Use Cases:**\n- Get query suggestions and refinements before asking\n- Understand how the system interprets your question\n- Get additional search terms for better results\n\n**Required Fields:**\n- `query`: The original query to improve\n\n**Optional Fields:**\n- `conversation_id`: ID of existing conversation for context\n\n**Response:**\n- `improved_query`: The enhanced version of the query\n- `search_terms`: Additional search terms extracted\n- `query_type`: Type of query (factual, analytical, etc.)\n- `reasoning`: Explanation of improvements made\n\n**Note:** This endpoint does not answer the question - it only improves the query. Use the 'Ask Question' endpoint to get answers." }, "response": [] }, { "name": "Ask Question", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.conversation_id) {", " pm.environment.set('conversation_id', jsonData.conversation_id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"question\": \"When does my passport expire?\",\n \"conversation_id\": \"{{conversation_id}}\",\n \"top_k\": 10,\n \"similarity_threshold\": 0.3,\n \"document_ids\": [],\n \"deep_research\": false,\n \"model\": \"gpt-5-mini\",\n \"sources\": [\"web\"]\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/vaults/{{vault_id}}/ask", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "ask" ] }, "description": "Ask a question about documents in a vault using RAG (Retrieval-Augmented Generation).\n\n**Required Fields:**\n- `question`: The question to ask\n\n**Optional Fields:**\n- `conversation_id`: ID of existing conversation to continue\n- `top_k`: Number of chunks to retrieve (default: 5, range: 1-50)\n- `similarity_threshold`: Minimum similarity score (default: 0.2, range: 0.0-1.0)\n - Lower values (0.2-0.3) return more results, useful for general questions\n - Higher values (0.5-0.7) return only highly similar results, useful for exact matches\n- `document_ids`: Array of document UUIDs to restrict search to (optional)\n - If provided, only search within the specified documents\n - If omitted or empty array, search all documents in the vault\n - Example: `[\"uuid1\", \"uuid2\", \"uuid3\"]`\n- `model`: LLM model to use (optional, default: \"gpt-5-mini\")\n - Available models: \"gpt-5.2\", \"gpt-5-mini\", \"gpt-4-turbo\", \"gpt-4\", \"gpt-3.5-turbo\"\n- `sources`: Array of search sources to enable (optional, default: [\"web\"])\n - Available sources: \"web\" (web search)\n\n**Response:** Returns AI-generated answer based on retrieved document chunks.\n\n**Note:** Requires documents to be uploaded and embeddings generated. Use Document Service embedding-stats endpoint to check if embeddings are ready.\n\n**Tip:** If you get \"no documents found\", try lowering the similarity_threshold to 0.2 or 0.3." }, "response": [] }, { "name": "Ask Question (Streaming)", "event": [ { "listen": "test", "script": { "exec": [ "// Note: Streaming responses are handled differently", "// The response will be a stream of Server-Sent Events (SSE)", "// In Postman, you'll see the events as they arrive", "console.log('Streaming response - check the response body for SSE events');" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "text/event-stream" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"question\": \"When does my passport expire?\",\n \"conversation_id\": \"{{conversation_id}}\",\n \"top_k\": 10,\n \"similarity_threshold\": 0.3,\n \"document_ids\": [],\n \"deep_research\": false,\n \"model\": \"gpt-5-mini\",\n \"sources\": [\"web\"]\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/vaults/{{vault_id}}/ask-stream", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "ask-stream" ] }, "description": "Ask a question about documents with real-time streaming response using Server-Sent Events (SSE).\n\n**Required Fields:**\n- `question`: The question to ask\n\n**Optional Fields:**\n- `conversation_id`: ID of existing conversation to continue\n- `top_k`: Number of chunks to retrieve (default: 5)\n- `similarity_threshold`: Minimum similarity score (default: 0.5)\n- `document_ids`: Array of document UUIDs to restrict search to\n- `model`: LLM model to use (optional, default: \"gpt-5-mini\")\n - Available models: \"gpt-5.2\", \"gpt-5-mini\", \"gpt-4-turbo\", \"gpt-4\", \"gpt-3.5-turbo\"\n- `sources`: Array of search sources to enable (optional, default: [\"web\"])\n - Available sources: \"web\" (web search)\n\n**Response:** Returns Server-Sent Events stream with real-time reasoning and answer.\n\n**Event Types:**\n- `reasoning_start`: Reasoning section begins\n- `reasoning_chunk`: Chunk of reasoning text (real-time)\n- `reasoning_end`: Reasoning section ends\n- `answer_start`: Answer section begins\n- `answer_chunk`: Chunk of answer text (real-time)\n- `answer_end`: Answer section ends\n- `metadata`: Source documents and conversation info\n- `message_saved`: Message ID after saving to conversation\n- `done`: Stream complete\n- `error`: An error occurred\n\n**Usage Notes:**\n- This endpoint streams the response in real-time, providing a better UX for long answers\n- The reasoning is shown first, followed by the answer\n- Source documents and metadata are sent before the answer begins\n- Best viewed with a client that supports SSE (e.g., frontend app, EventSource API)\n- Postman will show the raw SSE events in the response body\n\n**Headers:**\n- `Accept: text/event-stream` is recommended for SSE clients" }, "response": [] }, { "name": "Auto-fill Form", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"form_fields\": [\n {\"name\": \"firstName\", \"type\": \"text\", \"label\": \"Given Name\", \"required\": true},\n {\"name\": \"passportFile\", \"type\": \"file\", \"label\": \"Passport Copy\", \"isFileUpload\": true}\n ],\n \"form_context\": {\n \"formTitle\": \"I-20 Travel Request\",\n \"requiredDocuments\": [\"Passport\"]\n },\n \"page_url\": \"https://example.com/form\",\n \"page_title\": \"Immigration Form\"\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/vaults/{{vault_id}}/auto-fill", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "auto-fill" ] }, "description": "Analyze form fields and map them to vault documents for auto-fill. Used by browser extension to populate immigration forms from vault data." }, "response": [] }, { "name": "Generate Follow-ups", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"question\": \"When does my passport expire?\",\n \"answer\": \"Your passport expires on March 15, 2026.\"\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/vaults/{{vault_id}}/follow-ups", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "vaults", "{{vault_id}}", "follow-ups" ] }, "description": "Generate 4-5 contextual follow-up questions based on the last user question and assistant answer (Perplexity/ChatGPT-style)." }, "response": [] }, { "name": "Improve Prompt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"prompt\": \"Summarize this immigration notice for a dependent visa holder\",\n \"intent\": \"summarization\"\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/improve-prompt", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "improve-prompt" ] }, "description": "Improve a prompt for clarity and effectiveness before using it in a workflow or conversation." }, "response": [] }, { "name": "Conversations", "item": [ { "name": "Create Conversation", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.id) {", " pm.environment.set('conversation_id', jsonData.id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\",\n \"title\": \"My Conversation\"\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/conversations", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations" ] }, "description": "Create a new conversation for a vault.\n\n**Required Fields:**\n- `vault_id`: Vault ID to associate conversation with\n\n**Optional Fields:**\n- `title`: Conversation title" }, "response": [] }, { "name": "List Conversations", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/conversations?vault_id={{vault_id}}&limit=50&offset=0", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations" ], "query": [ { "key": "vault_id", "value": "{{vault_id}}", "description": "Optional: Filter by vault ID" }, { "key": "limit", "value": "50", "description": "Maximum number of conversations to return (1-100, default: 50)" }, { "key": "offset", "value": "0", "description": "Number of conversations to skip for pagination (default: 0)" } ] }, "description": "List user's conversations with pagination.\n\n**Query Parameters:**\n- `vault_id` (optional): Filter conversations by vault ID\n- `limit` (optional): Maximum number of conversations to return (1-100, default: 50)\n- `offset` (optional): Number of conversations to skip for pagination (default: 0)\n\n**Response:**\n- `conversations`: Array of conversation objects\n- `total`: Total number of conversations matching the filter" }, "response": [] }, { "name": "Get Conversation", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/conversations/{{conversation_id}}?include_messages=true", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations", "{{conversation_id}}" ], "query": [ { "key": "include_messages", "value": "true", "description": "Include message history", "disabled": false } ] }, "description": "Get conversation details with optional message history.\n\n**Query Parameters:**\n- `include_messages` (optional, default: false): Include message history in response" }, "response": [] }, { "name": "Delete Conversation", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/conversations/{{conversation_id}}", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations", "{{conversation_id}}" ] }, "description": "Delete a conversation (soft delete)." }, "response": [] }, { "name": "Update Conversation", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"title\": \"Updated Conversation Title\"\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/conversations/{{conversation_id}}", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations", "{{conversation_id}}" ] }, "description": "Update a conversation's title.\n\n**Body:**\n- `title`: New title for the conversation" }, "response": [] }, { "name": "Cleanup Old Conversations", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/conversations/cleanup?days=7", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations", "cleanup" ], "query": [ { "key": "days", "value": "7", "description": "Delete conversations older than X days (default: 7)" } ] }, "description": "Delete all conversations older than the specified number of days.\n\n**Query Parameters:**\n- `days` (optional, default: 7): Number of days. Conversations older than this will be permanently deleted." }, "response": [] }, { "name": "Delete All Conversations", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/conversations/all", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations", "all" ] }, "description": "Permanently delete all conversations for the authenticated user." }, "response": [] } ] }, { "name": "Configuration", "item": [ { "name": "List Models", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/models", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "models" ] }, "description": "List all available LLM models. Currently supports OpenAI models only.\n\n**Response:** Returns list of available models with their details (id, name, provider, description, context_length, availability)." }, "response": [] }, { "name": "List Sources", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/sources", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "sources" ] }, "description": "List all available search sources. Currently supports web search only.\n\n**Response:** Returns list of available sources with their details (id, name, description, enabled status, availability)." }, "response": [] } ] }, { "name": "News Discovery", "item": [ { "name": "List News Articles", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " console.log('Total articles: ' + jsonData.total);", " console.log('Has more: ' + jsonData.has_more);", " if (jsonData.articles && jsonData.articles.length > 0) {", " var firstArticle = jsonData.articles[0];", " pm.environment.set('article_id', firstArticle.id);", " console.log('First article: ' + firstArticle.title);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/news?limit=20&offset=0", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "news" ], "query": [ { "key": "limit", "value": "20", "description": "Number of articles to return (default: 20, max: 100)" }, { "key": "offset", "value": "0", "description": "Pagination offset (default: 0)" }, { "key": "category", "value": "policy", "description": "Filter by category: policy, visa, court, travel, general", "disabled": true }, { "key": "region", "value": "US", "description": "Filter by region: US, Canada, EU, Global", "disabled": true } ] }, "description": "List immigration news articles from RSS feeds.\n\n**Query Parameters:**\n- `limit` (optional): Number of articles to return (default: 20, max: 100)\n- `offset` (optional): Pagination offset (default: 0)\n- `category` (optional): Filter by category\n - `policy`: Policy updates and regulations\n - `visa`: Visa-related news (H-1B, green cards, etc.)\n - `court`: Court cases and legal rulings\n - `travel`: Travel and border news\n - `general`: General immigration news\n- `region` (optional): Filter by geographic region\n - `US`: United States\n - `Canada`: Canada\n - `EU`: European Union\n - `Global`: Global/international news\n\n**Response:**\n- `articles`: Array of news articles\n- `total`: Total number of articles matching the filter\n- `has_more`: Whether more articles are available\n\n**Note:** News is fetched automatically from RSS feeds every 30 minutes. Articles older than 30 days are automatically cleaned up." }, "response": [] }, { "name": "Get News Categories", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/news/categories", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "news", "categories" ] }, "description": "Get available news categories for filtering.\n\n**Response:**\n- `categories`: Array of category objects with:\n - `id`: Category identifier (e.g., 'policy', 'visa')\n - `label`: Display label (e.g., 'Policy Updates')\n - `icon`: Lucide icon name for UI display" }, "response": [] }, { "name": "Get News Regions", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/news/regions", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "news", "regions" ] }, "description": "Get available news regions for filtering.\n\n**Response:**\n- `regions`: Array of region objects with:\n - `id`: Region identifier (e.g., 'US', 'Canada')\n - `label`: Display label (e.g., 'United States')\n - `icon`: Lucide icon name for UI display" }, "response": [] }, { "name": "Get News Article", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/news/{{article_id}}", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "news", "{{article_id}}" ] }, "description": "Get a single news article by ID.\n\n**Path Parameters:**\n- `article_id`: UUID of the news article\n\n**Response:**\n- `article`: News article object with:\n - `id`: Article UUID\n - `title`: Article headline\n - `description`: Article summary/excerpt\n - `url`: Link to original article\n - `source_name`: Name of the source (e.g., 'USCIS', 'Reuters')\n - `source_url`: URL of the source website\n - `image_url`: Article thumbnail image URL\n - `published_at`: Publication date (ISO 8601)\n - `category`: Article category (policy, visa, court, travel, general)\n - `region`: Geographic region (US, Canada, EU, Global)\n - `created_at`: When article was added to the database" }, "response": [] } ] }, { "name": "Workflows", "item": [ { "name": "List Workflows", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.workflows && jsonData.workflows.length > 0) {", " var firstWorkflow = jsonData.workflows[0];", " if (firstWorkflow.id) {", " pm.environment.set('workflow_id', firstWorkflow.id);", " }", " console.log('Found ' + jsonData.workflows.length + ' workflows');", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflows?category=translation", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows" ], "query": [ { "key": "category", "value": "translation", "description": "Optional: Filter workflows by category (e.g., 'translation', 'visa', 'university')", "disabled": true } ] }, "description": "List all available workflows.\n\n**Query Parameters:**\n- `category` (optional): Filter workflows by category (e.g., 'translation', 'visa', 'university')\n\n**Response:** Returns list of workflows with metadata:\n- `id`: Workflow UUID\n- `name`: Workflow name\n- `description`: Workflow description\n- `category`: Workflow category\n- `icon`: Icon identifier\n- `output_type`: Type of output ('output', 'draft', 'table')\n- `step_count`: Number of steps (e.g., '2 steps')\n- `is_active`: Whether workflow is active\n\n**Note:** Workflows are pre-defined and seeded in the database. Use the workflow ID to start an execution." }, "response": [] }, { "name": "Get Workflow Details", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflows/{{workflow_name}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows", "{{workflow_name}}" ] }, "description": "Get detailed information about a specific workflow, including all steps.\n\n**Path Parameters:**\n- `workflow_id`: UUID of the workflow\n\n**Response:** Returns workflow details including:\n- Basic workflow metadata\n- `steps`: Array of workflow steps with:\n - `step_order`: Order in sequence (1, 2, 3...)\n - `step_type`: Type of step ('UPLOAD_FILES', 'SELECT_OPTION', 'AI_TRANSLATE', etc.)\n - `name`: Step display name\n - `description`: Step instructions\n - `prompt`: AI prompt (for AI steps)\n - `config`: Step-specific configuration (JSON)\n - `is_optional`: Whether step can be skipped\n\n**Use Cases:**\n- Preview workflow steps before execution\n- Understand what inputs are required\n- See AI prompts for transparency" }, "response": [] }, { "name": "Start Workflow Execution", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.id) {", " pm.environment.set('workflow_execution_id', jsonData.id);", " console.log('Workflow execution started: ' + jsonData.id);", " console.log('Status: ' + jsonData.status);", " if (jsonData.step_executions && jsonData.step_executions.length > 0) {", " console.log('Total steps: ' + jsonData.step_executions.length);", " }", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\"\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/workflows/{{workflow_name}}/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows", "{{workflow_name}}", "execute" ] }, "description": "Start a new workflow execution.\n\n**Path Parameters:**\n- `workflow_id`: UUID of the workflow to execute\n\n**Required Fields:**\n- `vault_id`: Vault ID where documents will be stored and processed\n\n**Response:** Returns execution details:\n- `id`: Execution UUID (save this for tracking progress)\n- `workflow_id`: Workflow that was started\n- `vault_id`: Vault where execution is running\n- `status`: Current status ('pending', 'in_progress', 'completed', 'failed')\n- `step_executions`: Array of step execution records (all start as 'pending')\n\n**Workflow Execution Flow:**\n1. Create execution (this endpoint) - status: 'pending'\n2. Execute steps sequentially:\n - Step 1: User uploads files \u2192 status: 'completed'\n - Step 2: User selects option \u2192 status: 'completed'\n - Step 3: AI processes \u2192 status: 'in_progress' \u2192 'completed'\n3. Execution complete - status: 'completed'\n\n**Note:** After creating an execution, you'll need to complete each step through the frontend or additional API endpoints (to be implemented). Use the 'Get Workflow Execution' endpoint to check progress." }, "response": [] }, { "name": "Get Workflow Execution", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflow-executions/{{workflow_execution_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflow-executions", "{{workflow_execution_id}}" ] }, "description": "Get the current status and details of a workflow execution.\n\n**Path Parameters:**\n- `workflow_execution_id`: UUID of the execution\n\n**Response:** Returns execution details including:\n- `id`: Execution UUID\n- `workflow_id`: Workflow being executed\n- `vault_id`: Vault where execution is running\n- `status`: Current status ('pending', 'in_progress', 'completed', 'failed')\n- `execution_context`: JSON object with accumulated data from completed steps\n- `step_executions`: Array of step execution details:\n - `step_order`: Step number in sequence\n - `status`: Step status ('pending', 'in_progress', 'completed', 'failed', 'skipped')\n - `input_data`: Step inputs (JSON)\n - `output_data`: Step outputs (JSON, e.g., document IDs, selected options)\n - `error_message`: Error if step failed\n - `started_at`: When step started\n - `completed_at`: When step completed\n- `started_at`: When execution started\n- `completed_at`: When execution completed\n- `error_message`: Error if execution failed\n\n**Use Cases:**\n- Poll for execution progress\n- Check which steps are complete\n- Retrieve outputs from completed steps (e.g., document IDs)\n- Debug failed executions\n\n**Polling Recommendation:** Poll every 1-2 seconds while execution is 'in_progress'" }, "response": [] }, { "name": "Complete Workflow Step", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"document_ids\": [\"{{document_id}}\"],\n \"selected_option\": \"option_value\",\n \"text_input\": \"User input text\"\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/workflow-executions/{{workflow_execution_id}}/steps/{{step_execution_id}}/complete", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflow-executions", "{{workflow_execution_id}}", "steps", "{{step_execution_id}}", "complete" ] }, "description": "Complete a user-driven workflow step (UPLOAD_FILES, SELECT_OPTION, INPUT_TEXT).\n\n**Path Parameters:**\n- `execution_id`: Workflow execution UUID\n- `step_execution_id`: Step execution UUID\n\n**Request Body:**\n- For UPLOAD_FILES: `{\"document_ids\": [\"uuid1\", \"uuid2\"]}`\n- For SELECT_OPTION: `{\"selected_option\": \"option_value\"}`\n- For INPUT_TEXT: `{\"text_input\": \"user text\"}`\n\n**Response:** Returns updated step execution with status 'completed' and output data." }, "response": [] }, { "name": "Execute Workflow Step", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflow-executions/{{workflow_execution_id}}/steps/{{step_execution_id}}/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflow-executions", "{{workflow_execution_id}}", "steps", "{{step_execution_id}}", "execute" ] }, "description": "Execute an AI-driven workflow step (AI_TRANSLATE, AI_PROCESS, AI_DRAFT).\n\n**Path Parameters:**\n- `execution_id`: Workflow execution UUID\n- `step_execution_id`: Step execution UUID\n\n**Response:** Returns step execution with AI processing results. Status will be 'in_progress' then 'completed' when done." }, "response": [] }, { "name": "Execute Workflow Step", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflow-executions/{{workflow_execution_id}}/steps/{{step_execution_id}}/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflow-executions", "{{workflow_execution_id}}", "steps", "{{step_execution_id}}", "execute" ] }, "description": "Reset workflow execution from a specific step. Resets the specified step and all subsequent steps to 'pending' status.\n\n**Path Parameters:**\n- `execution_id`: Workflow execution UUID\n- `step_execution_id`: Step execution UUID to reset from\n\n**Response:** Returns reset confirmation with count of steps reset." }, "response": [] } ] }, { "name": "Prompt Library", "item": [ { "name": "List Prompts", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/prompts", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "prompts" ], "query": [ { "key": "category", "value": "work", "description": "Filter by category (work, student, general, travel, system)", "disabled": true }, { "key": "search", "value": "H-1B", "description": "Search query to filter prompts", "disabled": true } ] }, "description": "List all available immigration prompts from the prompt library.\n\n**Optional Query Parameters:**\n- `category`: Filter by category (work, student, general, travel, system)\n- `search`: Search query to filter prompts by title, content, or document types\n\n**Response:**\n- `prompts`: Array of prompt objects with id, category, title, role, prompt text, and required documents\n- `categories`: Array of category objects with id, label, icon, and color\n- `total`: Total number of prompts returned" }, "response": [] }, { "name": "List Prompts (by Category)", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/prompts?category=work", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "prompts" ], "query": [ { "key": "category", "value": "work" } ] }, "description": "List prompts filtered by category.\n\n**Categories:**\n- `work`: Work visa prompts (H-1B, green card, etc.)\n- `student`: Student visa prompts (F-1, OPT, CPT, etc.)\n- `general`: General immigration prompts\n- `travel`: Travel-related prompts\n- `system`: Power tools and advanced prompts" }, "response": [] }, { "name": "Get Prompt by ID", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/prompts/WORK_001", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "prompts", "WORK_001" ] }, "description": "Get a specific prompt by its ID.\n\n**Path Parameters:**\n- `prompt_id`: The prompt ID (e.g., WORK_001, STUDENT_001, GENERAL_001, TRAVEL_001, SYSTEM_001)\n\n**Response:**\n- `prompt`: Full prompt object with id, category, title, role, prompt text, and required documents" }, "response": [] }, { "name": "Track Prompt Usage", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/prompts/WORK_001/use", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "prompts", "WORK_001", "use" ] }, "description": "Track usage of a prompt (increment usage counter for analytics).\n\n**Path Parameters:**\n- `prompt_id`: The prompt ID to track\n\n**Response:**\n- `success`: Boolean indicating if tracking was successful\n- `prompt_id`: The prompt ID that was tracked\n\n**Note:** This endpoint is called automatically by the frontend when a user selects a prompt." }, "response": [] } ] }, { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{assistant_base_url}}/health", "host": [ "{{assistant_base_url}}" ], "path": [ "health" ] }, "description": "Service health check endpoint." }, "response": [] } ] }, { "name": "Workflow Service", "description": "Multi-step workflow orchestration service. Provides class-based workflows with decorator-driven step definitions.\n\n**Port:** 8006\n\n**Features:**\n- List available workflows\n- Execute workflows with vault context\n- Continue workflows with user input\n- View workflow registry", "item": [ { "name": "Workflows", "item": [ { "name": "List Workflows", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.workflows && jsonData.workflows.length > 0) {", " pm.environment.set('workflow_name', jsonData.workflows[0].name);", " console.log('Set workflow_name to: ' + jsonData.workflows[0].name);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/workflows", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows" ] }, "description": "List all available workflows.\n\n**Query Parameters:**\n- `category` (optional): Filter by category (e.g., 'student', 'visa', 'travel', 'general')\n\n**Response:**\n- `workflows`: Array of workflow objects with name, description, steps, required_documents" }, "response": [] }, { "name": "List Workflows by Category", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflows?category=student", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "workflows" ], "query": [ { "key": "category", "value": "student" } ] }, "description": "List workflows filtered by category.\n\n**Categories:**\n- `student`: F-1/OPT related workflows\n- `visa`: Visa application workflows\n- `travel`: Travel history and I-94 workflows\n- `employment`: I-9 verification\n- `general`: Translation, credit card, etc." }, "response": [] }, { "name": "Get Workflow Details", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflows/{{workflow_name}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows", "{{workflow_name}}" ] }, "description": "Get details of a specific workflow by name.\n\n**Path Parameters:**\n- `workflow_name`: The workflow name (e.g., 'Get a Travel I-20', 'Translate Document')\n\n**Response:**\n- `name`: Workflow name\n- `description`: Full description\n- `steps`: Array of step definitions\n- `required_documents`: Documents needed for workflow" }, "response": [] } ] }, { "name": "Workflow Execution", "item": [ { "name": "Execute Workflow", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.id) {", " pm.environment.set('execution_id', jsonData.id);", " console.log('Set execution_id to: ' + jsonData.id);", " }", " if (jsonData.step_executions && jsonData.step_executions.length > 0) {", " pm.environment.set('step_execution_id', jsonData.step_executions[0].id);", " console.log('Set step_execution_id to: ' + jsonData.step_executions[0].id);", " }", " if (jsonData.state) {", " pm.environment.set('workflow_state', JSON.stringify(jsonData.state));", " }", " console.log('Workflow execution started. Status: ' + jsonData.status);", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\",\n \"initial_context\": {}\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/workflows/{{workflow_name}}/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows", "{{workflow_name}}", "execute" ] }, "description": "Start a new workflow execution.\n\n**Path Parameters:**\n- `workflow_name`: Name of workflow to execute\n\n**Body:**\n- `vault_id`: ID of the vault containing documents\n- `initial_context` (optional): Initial context data\n\n**Response:**\n- `success`: Boolean\n- `execution`: Current execution state\n - `status`: 'waiting_user', 'completed', or 'error'\n - `current_step`: Current step number\n - `step_config`: Configuration for user input step (if waiting)\n- `state`: Full executor state (save this for continue_workflow)" }, "response": [] }, { "name": "Execute Translate Document Workflow", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\",\n \"initial_context\": {}\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/workflows/Translate Document/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows", "Translate Document", "execute" ] }, "description": "Execute the Translate Document workflow.\n\n**Steps:**\n1. Upload Document (upload_files)\n2. Choose Language (select_option)\n3. Translate Document (ai_translate)" }, "response": [] }, { "name": "Execute Travel I-20 Workflow", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\",\n \"initial_context\": {}\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/workflows/Get a Travel I-20/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows", "Get a Travel I-20", "execute" ] }, "description": "Execute the Travel I-20 workflow.\n\n**Steps:**\n1. Check Documents (ai_process)\n2. Upload Documents (upload_files)\n3. Verify Documents (ai_process)\n4. Current Status (select_option)\n5. Departure Date (user_input)\n6. Return Date (user_input)\n7. Countries (select_option)\n8. Purpose (user_input)\n9. ISO Email (user_input)\n10. Generate Email (ai_draft)\n11. Send Email (send_email)" }, "response": [] }, { "name": "Execute Travel History Workflow", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\",\n \"initial_context\": {}\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/workflows/Get My Travel History/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows", "Get My Travel History", "execute" ] }, "description": "Execute the Travel History workflow.\n\n**Steps:**\n1. Check Documents (ai_process)\n2. Upload Documents (upload_files)\n3. Verify Documents (ai_process)\n4. Generate Travel History (ai_draft)\n\n**Required Documents:**\n- I-94 Arrival/Departure Record\n- Passport Bio Page" }, "response": [] }, { "name": "Get Execution Status", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " if (jsonData.step_executions && jsonData.step_executions.length > 0) {", " // Find first pending step", " var pendingStep = jsonData.step_executions.find(s => s.status === 'pending');", " if (pendingStep) {", " pm.environment.set('step_execution_id', pendingStep.id);", " console.log('Set step_execution_id to: ' + pendingStep.id);", " }", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflow-executions/{{execution_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflow-executions", "{{execution_id}}" ] }, "description": "Get the current status of a workflow execution.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n\n**Response:**\n- `id`: Execution UUID\n- `workflow_name`: Name of the workflow\n- `status`: Current status (awaiting_input, running, completed, failed)\n- `step_executions`: Array of step execution details\n - `id`: Step execution UUID\n - `step_order`: Order of the step\n - `step_type`: Type (upload_files, select_option, ai_translate, etc.)\n - `status`: pending, in_progress, completed, failed\n - `input_data`: User input data\n - `output_data`: Step output (e.g., translated_text)" }, "response": [] }, { "name": "Complete Step with User Input", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "body": { "mode": "raw", "raw": "{\n \"document_ids\": [\"{{document_id}}\"],\n \"selected_option\": \"Spanish\"\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/workflow-executions/{{execution_id}}/steps/{{step_execution_id}}/complete", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflow-executions", "{{execution_id}}", "steps", "{{step_execution_id}}", "complete" ] }, "description": "Complete a workflow step with user input.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n- `step_execution_id`: UUID of the step execution\n\n**Body (varies by step type):**\n\n*For upload_files steps:*\n```json\n{ \"document_ids\": [\"uuid1\", \"uuid2\"] }\n```\n\n*For select_option steps:*\n```json\n{ \"selected_option\": \"Spanish\" }\n```\n\n*For user_input steps:*\n```json\n{ \"text\": \"user provided text\" }\n```\n\n**Response:**\n- `success`: Boolean\n- `step_execution`: Updated step execution details" }, "response": [] }, { "name": "Execute AI Step", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}", "type": "text" } ], "url": { "raw": "{{workflow_base_url}}/api/v1/workflow-executions/{{execution_id}}/steps/{{step_execution_id}}/execute", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflow-executions", "{{execution_id}}", "steps", "{{step_execution_id}}", "execute" ] }, "description": "Execute an AI-powered workflow step.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n- `step_execution_id`: UUID of the step execution\n\n**Step Types:**\n- `ai_process`: Process and analyze documents\n- `ai_translate`: Translate document content\n- `ai_draft`: Generate text (emails, letters, etc.)\n- `ai_extract`: Extract structured data from documents\n\n**Response:**\n- `success`: Boolean\n- `step_execution`: Updated step with output_data\n- `result`: Full execution result including translated_text, etc." }, "response": [] } ] }, { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/health", "host": [ "{{workflow_base_url}}" ], "path": [ "health" ] }, "description": "Service health check endpoint." }, "response": [] } ] }, { "name": "Workflow Engine V2", "description": "Extensible workflow engine with policy-driven execution. Provides a more flexible and powerful workflow system with step templates, policies, and dynamic execution.\n\n**Port:** 8006 (same as Workflow Service)\n\n**Features:**\n- Step templates for reusable workflow components\n- Policy-driven execution rules\n- Event injection for dynamic workflow behavior\n- Pause/Resume/Cancel execution control", "item": [ { "name": "Workflows", "item": [ { "name": "List Workflows (V2)", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/workflows", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "workflows" ], "query": [ { "key": "category", "value": "student", "description": "Optional: Filter by category", "disabled": true }, { "key": "include_inactive", "value": "false", "description": "Optional: Include inactive workflows (default: false)", "disabled": true } ] }, "description": "List all workflows from the V2 engine.\n\n**Query Parameters:**\n- `category` (optional): Filter by category\n- `include_inactive` (optional, default: false): Include inactive workflows\n\n**Response:**\n- `workflows`: Array of workflow objects" }, "response": [] }, { "name": "Get Workflow (V2)", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/workflows/{{workflow_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "workflows", "{{workflow_id}}" ] }, "description": "Get a specific workflow by ID.\n\n**Path Parameters:**\n- `workflow_id`: UUID of the workflow\n\n**Response:** Returns the workflow object with all details." }, "response": [] } ] }, { "name": "Step Templates", "item": [ { "name": "List Step Templates", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/steps", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "steps" ], "query": [ { "key": "step_type", "value": "ai_process", "description": "Optional: Filter by step type", "disabled": true } ] }, "description": "List all available step templates.\n\n**Query Parameters:**\n- `step_type` (optional): Filter by step type (e.g., 'ai_process', 'upload_files', 'select_option')\n\n**Response:**\n- `steps`: Array of step template objects" }, "response": [] } ] }, { "name": "Policies", "item": [ { "name": "List Policies", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/policies", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "policies" ], "query": [ { "key": "jurisdiction", "value": "US", "description": "Optional: Filter by jurisdiction", "disabled": true } ] }, "description": "List all available policies.\n\n**Query Parameters:**\n- `jurisdiction` (optional): Filter by jurisdiction (e.g., 'US', 'EU')\n\n**Response:**\n- `policies`: Array of policy objects" }, "response": [] }, { "name": "Get Policy", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/policies/{{policy_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "policies", "{{policy_id}}" ] }, "description": "Get a specific policy by ID.\n\n**Path Parameters:**\n- `policy_id`: ID of the policy\n\n**Response:** Returns the policy object." }, "response": [] }, { "name": "Evaluate Policy", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"policy_id\": \"immigration_eligibility\",\n \"context\": {\n \"visa_type\": \"F-1\",\n \"days_in_us\": 180\n }\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/engine/policies/evaluate", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "policies", "evaluate" ] }, "description": "Evaluate a policy against a given context.\n\n**Request Body:**\n- `policy_id`: ID of the policy to evaluate\n- `context`: Object containing context data for evaluation\n\n**Response:** Returns the evaluation result." }, "response": [] }, { "name": "Evaluate Expression", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"expression\": \"context.days_in_us < 183 and context.visa_type == 'F-1'\",\n \"context\": {\n \"visa_type\": \"F-1\",\n \"days_in_us\": 180\n }\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/engine/policies/evaluate-expression", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "policies", "evaluate-expression" ] }, "description": "Evaluate a policy expression against a given context.\n\n**Request Body:**\n- `expression`: Policy expression string to evaluate\n- `context`: Object containing context data for evaluation\n\n**Response:**\n- `result`: Evaluation result (boolean or value)" }, "response": [] } ] }, { "name": "Executions", "item": [ { "name": "Start Execution (V2)", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200 || pm.response.code === 201) {", " var jsonData = pm.response.json();", " if (jsonData.execution_id) {", " pm.environment.set('v2_execution_id', jsonData.execution_id);", " console.log('V2 execution started: ' + jsonData.execution_id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"workflow_id\": \"{{workflow_id}}\",\n \"vault_id\": \"{{vault_id}}\",\n \"initial_context\": \"{}\"\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions?account_id={{user_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions" ], "query": [ { "key": "account_id", "value": "{{user_id}}", "description": "Required: Account ID" } ] }, "description": "Start a new workflow execution using the V2 engine.\n\n**Query Parameters:**\n- `account_id` (required): Account ID of the user\n\n**Request Body:**\n- `workflow_id`: UUID of the workflow to execute\n- `vault_id`: UUID of the vault\n- `initial_context` (optional): JSON string of initial context data\n\n**Response:**\n- `success`: Boolean\n- `execution_id`: UUID of the created execution" }, "response": [] }, { "name": "List Executions (V2)", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions?account_id={{user_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions" ], "query": [ { "key": "account_id", "value": "{{user_id}}", "description": "Required: Account ID" }, { "key": "status", "value": "running", "description": "Optional: Filter by status (pending, running, completed, failed)", "disabled": true } ] }, "description": "List all workflow executions for an account.\n\n**Query Parameters:**\n- `account_id` (required): Account ID\n- `status` (optional): Filter by status (pending, running, completed, failed)\n\n**Response:**\n- `executions`: Array of execution objects" }, "response": [] }, { "name": "Get Execution (V2)", "request": { "method": "GET", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions/{{v2_execution_id}}?account_id={{user_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions", "{{v2_execution_id}}" ], "query": [ { "key": "account_id", "value": "{{user_id}}", "description": "Required: Account ID" } ] }, "description": "Get details of a specific execution.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n\n**Query Parameters:**\n- `account_id` (required): Account ID\n\n**Response:** Returns full execution details including step statuses." }, "response": [] }, { "name": "Complete Step (V2)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"input_data\": {\n \"document_ids\": [\"{{document_id}}\"],\n \"selected_option\": \"Spanish\"\n }\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions/{{v2_execution_id}}/steps/{{v2_step_execution_id}}/complete?account_id={{user_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions", "{{v2_execution_id}}", "steps", "{{v2_step_execution_id}}", "complete" ], "query": [ { "key": "account_id", "value": "{{user_id}}", "description": "Required: Account ID" } ] }, "description": "Complete a step with user input.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n- `step_execution_id`: UUID of the step execution\n\n**Query Parameters:**\n- `account_id` (required): Account ID\n\n**Request Body:**\n- `input_data`: Object containing user input for the step" }, "response": [] }, { "name": "Execute AI Step (V2)", "request": { "method": "POST", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions/{{v2_execution_id}}/steps/{{v2_step_execution_id}}/execute?account_id={{user_id}}", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions", "{{v2_execution_id}}", "steps", "{{v2_step_execution_id}}", "execute" ], "query": [ { "key": "account_id", "value": "{{user_id}}", "description": "Required: Account ID" } ] }, "description": "Execute an AI-powered step.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n- `step_execution_id`: UUID of the step execution\n\n**Query Parameters:**\n- `account_id` (required): Account ID" }, "response": [] }, { "name": "Pause Execution", "request": { "method": "POST", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions/{{v2_execution_id}}/pause", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions", "{{v2_execution_id}}", "pause" ] }, "description": "Pause a running execution.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n\n**Response:** Returns updated execution status." }, "response": [] }, { "name": "Resume Execution", "request": { "method": "POST", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions/{{v2_execution_id}}/resume", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions", "{{v2_execution_id}}", "resume" ] }, "description": "Resume a paused execution.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n\n**Response:** Returns updated execution status." }, "response": [] }, { "name": "Cancel Execution", "request": { "method": "POST", "header": [], "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions/{{v2_execution_id}}/cancel", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions", "{{v2_execution_id}}", "cancel" ] }, "description": "Cancel an execution.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n\n**Response:** Returns updated execution status." }, "response": [] }, { "name": "Inject Event", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"event_name\": \"document_uploaded\",\n \"event_data\": {\n \"document_id\": \"{{document_id}}\",\n \"document_type\": \"PASSPORT\"\n }\n}" }, "url": { "raw": "{{workflow_base_url}}/api/v1/engine/executions/{{v2_execution_id}}/events", "host": [ "{{workflow_base_url}}" ], "path": [ "api", "v1", "engine", "executions", "{{v2_execution_id}}", "events" ] }, "description": "Inject an event into an execution for dynamic workflow behavior.\n\n**Path Parameters:**\n- `execution_id`: UUID of the execution\n\n**Request Body:**\n- `event_name`: Name of the event to inject\n- `event_data`: Object containing event-specific data\n\n**Response:** Returns the result of event processing." }, "response": [] } ] } ] }, { "name": "MCP Service", "description": "MCP proxy service for extension/chat tooling and cross-service forwarding.\n\n**Port:** 8007\n\n**Features:**\n- Chat forwarding with page context\n- MCP tool discovery/execution\n- Generic route proxy to downstream services", "item": [ { "name": "Health Check", "request": { "method": "GET", "header": [], "url": { "raw": "{{mcp_base_url}}/health", "host": [ "{{mcp_base_url}}" ], "path": [ "health" ] }, "description": "Service health check endpoint." }, "response": [] }, { "name": "Chat Routes", "item": [ { "name": "Send Message", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"question\": \"What does my latest I-20 say about travel signatures?\",\n \"vault_id\": \"{{vault_id}}\",\n \"deep_research\": false,\n \"model\": \"gpt-5-mini\",\n \"conversation_id\": \"{{conversation_id}}\",\n \"page_context\": {\n \"url\": \"https://www.uscis.gov\",\n \"title\": \"USCIS Travel Guidance\",\n \"domain\": \"uscis.gov\",\n \"text_content\": \"Travel signatures are typically required...\",\n \"is_immigration_site\": true\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/chat/message", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "chat", "message" ] }, "description": "Non-streaming chat request via MCP service." }, "response": [] }, { "name": "Send Message (Streaming)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "text/event-stream" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"question\": \"Summarize my visa expiry timeline\",\n \"vault_id\": \"{{vault_id}}\",\n \"deep_research\": true,\n \"model\": \"auto\",\n \"conversation_id\": \"{{conversation_id}}\"\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/chat/message/stream", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "chat", "message", "stream" ] }, "description": "Streaming chat request (SSE) via MCP service." }, "response": [] } ] }, { "name": "MCP Tool Routes", "item": [ { "name": "List Tools", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools" ] } }, "response": [] }, { "name": "Get Tool - ask_question", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/ask_question", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "ask_question" ] } }, "response": [] }, { "name": "Execute - list_vaults", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {}\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/list_vaults/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "list_vaults", "execute" ] } }, "response": [] }, { "name": "Execute - search_documents", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"vault_id\": \"{{vault_id}}\",\n \"query\": \"passport expiry\",\n \"top_k\": 10\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/search_documents/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "search_documents", "execute" ] } }, "response": [] }, { "name": "Execute - get_vault_documents", "event": [ { "listen": "test", "script": { "exec": [ "if (pm.response.code === 200) {", " var jsonData = pm.response.json();", " var docs = [];", " if (jsonData.data && jsonData.data.documents) {", " docs = jsonData.data.documents;", " } else if (jsonData.documents) {", " docs = jsonData.documents;", " }", " if (docs.length > 0 && docs[0].id) {", " pm.environment.set('document_id', docs[0].id);", " console.log('Set document_id to: ' + docs[0].id);", " }", "}" ], "type": "text/javascript" } } ], "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"vault_id\": \"{{vault_id}}\"\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/get_vault_documents/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "get_vault_documents", "execute" ] } }, "response": [] }, { "name": "Execute - get_document", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"document_id\": \"{{document_id}}\"\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/get_document/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "get_document", "execute" ] } }, "response": [] }, { "name": "Execute - ask_question", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"vault_id\": \"{{vault_id}}\",\n \"question\": \"What are my next immigration deadlines?\",\n \"deep_research\": false\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/ask_question/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "ask_question", "execute" ] } }, "response": [] }, { "name": "Execute - get_download_link", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"document_id\": \"{{document_id}}\"\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/get_download_link/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "get_download_link", "execute" ] } }, "response": [] }, { "name": "Execute - auto_fill_form", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"vault_id\": \"{{vault_id}}\",\n \"form_fields\": [\n {\n \"name\": \"firstName\",\n \"type\": \"text\",\n \"id\": \"first-name\",\n \"label\": \"Given Name\",\n \"required\": true,\n \"isFileUpload\": false\n },\n {\n \"name\": \"passportFile\",\n \"type\": \"file\",\n \"id\": \"passport-upload\",\n \"label\": \"Passport Copy\",\n \"required\": false,\n \"isFileUpload\": true,\n \"acceptedFileTypes\": \".pdf,.jpg\"\n }\n ],\n \"form_context\": {\n \"pageTitle\": \"Immigration Form\",\n \"formTitle\": \"I-20 Travel Request\",\n \"sections\": [],\n \"instructions\": [],\n \"requiredDocuments\": [\"Passport\"]\n },\n \"page_url\": \"https://example.com/form\",\n \"page_title\": \"I-20 Travel Request\"\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/auto_fill_form/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "auto_fill_form", "execute" ] } }, "response": [] }, { "name": "Execute - improve_prompt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"prompt\": \"What should I do next for my visa?\",\n \"page_context\": \"User is reading USCIS status page\"\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/improve_prompt/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "improve_prompt", "execute" ] } }, "response": [] }, { "name": "Execute - proxy_request", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"params\": {\n \"service\": \"workflow\",\n \"method\": \"GET\",\n \"path\": \"/api/v1/workflows\",\n \"query\": {\n \"category\": \"student\"\n }\n }\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/mcp/tools/proxy_request/execute", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "mcp", "tools", "proxy_request", "execute" ] }, "description": "Dynamic tool that can call any downstream service and route." }, "response": [] } ] }, { "name": "Generic Proxy Routes", "item": [ { "name": "Proxy GET - Workflow List", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_base_url}}/api/v1/proxy/workflow/api/v1/workflows?category=student", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "proxy", "workflow", "api", "v1", "workflows" ], "query": [ { "key": "category", "value": "student" } ] } }, "response": [] }, { "name": "Proxy POST - Improve Prompt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"prompt\": \"Improve this question\",\n \"page_context\": \"USCIS page\"\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/proxy/assistant/api/v1/improve-prompt", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "proxy", "assistant", "api", "v1", "improve-prompt" ] } }, "response": [] }, { "name": "Proxy PATCH - Update Person", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"first_name\": \"Updated\",\n \"last_name\": \"Name\"\n}" }, "url": { "raw": "{{mcp_base_url}}/api/v1/proxy/immigration/api/v1/persons/{{person_id}}", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "proxy", "immigration", "api", "v1", "persons", "{{person_id}}" ] } }, "response": [] }, { "name": "Proxy DELETE - Status", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{mcp_base_url}}/api/v1/proxy/immigration/api/v1/statuses/{{status_id}}", "host": [ "{{mcp_base_url}}" ], "path": [ "api", "v1", "proxy", "immigration", "api", "v1", "statuses", "{{status_id}}" ] } }, "response": [] } ] } ] }, { "name": "Immigration Service", "item": [ { "name": "Create Person", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"organization_id\": \"{{organization_id}}\",\n \"first_name\": \"Test\",\n \"last_name\": \"Student\",\n \"email\": \"student@example.com\"\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/persons", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons" ] } }, "response": [] }, { "name": "List Persons", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons" ] } }, "response": [] }, { "name": "Get Person", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}" ] } }, "response": [] }, { "name": "Patch Person", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"first_name\": \"Updated\"\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}" ] } }, "response": [] }, { "name": "Delete Person", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}" ] } }, "response": [] }, { "name": "List Persons (organization from JWT)", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons" ] } }, "response": [] }, { "name": "Create Status", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"status_type\": \"F1\",\n \"status_value\": \"active\"\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}/statuses", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}", "statuses" ] } }, "response": [] }, { "name": "List Statuses", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}/statuses", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}", "statuses" ] } }, "response": [] }, { "name": "Get Status", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/statuses/{{status_id}}", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "statuses", "{{status_id}}" ] } }, "response": [] }, { "name": "Patch Status", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"notes\": \"updated by postman\"\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/statuses/{{status_id}}", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "statuses", "{{status_id}}" ] } }, "response": [] }, { "name": "Delete Status", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/statuses/{{status_id}}", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "statuses", "{{status_id}}" ] } }, "response": [] }, { "name": "Get Compliance Summary", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}/compliance-summary", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}", "compliance-summary" ] } }, "response": [] }, { "name": "List Compliance Events", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}/compliance-events", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}", "compliance-events" ] } }, "response": [] }, { "name": "Create Compliance Event", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"event_type\": \"status.expiring\",\n \"severity\": \"high\",\n \"details\": \"Expiring in 30 days\"\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}/compliance-events", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}", "compliance-events" ] } }, "response": [] }, { "name": "Upload Person Document", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"filename\": \"passport.pdf\",\n \"content_type\": \"application/pdf\",\n \"metadata\": {\"document_type\": \"passport\"}\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}/documents", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}", "documents" ] }, "description": "Record document metadata for a person. Stores filename and metadata in person record (document content stored via Document Service)." }, "response": [] }, { "name": "List Person Documents", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{immigration_base_url}}/api/v1/persons/{{person_id}}/documents", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "persons", "{{person_id}}", "documents" ] }, "description": "List document metadata records associated with a person." }, "response": [] }, { "name": "Import Persons", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"source\": \"csv\",\n \"payload\": {}\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/import/persons", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "import", "persons" ] } }, "response": [] }, { "name": "Import Statuses", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"source\": \"csv\",\n \"payload\": {}\n}" }, "url": { "raw": "{{immigration_base_url}}/api/v1/import/statuses", "host": [ "{{immigration_base_url}}" ], "path": [ "api", "v1", "import", "statuses" ] } }, "response": [] } ] }, { "name": "Organization Service", "item": [ { "name": "Create Organization", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Test University\",\n \"slug\": \"test-university\"\n}" }, "url": { "raw": "{{organization_base_url}}/api/v1/organizations", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations" ] } }, "response": [] }, { "name": "List Organizations", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations" ] } }, "response": [] }, { "name": "Get Organization", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}" ] } }, "response": [] }, { "name": "Patch Organization", "request": { "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Updated University\"\n}" }, "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}" ] } }, "response": [] }, { "name": "Add Member", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"user_id\": \"{{user_id}}\",\n \"role\": \"admin\"\n}" }, "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/members", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "members" ] } }, "response": [] }, { "name": "List Members", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/members", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "members" ] } }, "response": [] }, { "name": "Delete Member", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/members/{{member_id}}", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "members", "{{member_id}}" ] } }, "response": [] }, { "name": "Machine Auth", "item": [ { "name": "Create Service Account", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"Integration Service Account\"\n}" }, "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/service-accounts", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "service-accounts" ] } }, "response": [] }, { "name": "List Service Accounts", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/service-accounts", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "service-accounts" ] } }, "response": [] }, { "name": "Deactivate Service Account", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/service-accounts/{{service_account_id}}/deactivate", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "service-accounts", "{{service_account_id}}", "deactivate" ] } }, "response": [] }, { "name": "Create API Key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"integration-key\",\n \"scopes\": [\"webhook:events:write\", \"immigration:imports:write\"]\n}" }, "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/api-keys", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "api-keys" ] } }, "response": [] }, { "name": "List API Keys", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/api-keys", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "api-keys" ] } }, "response": [] }, { "name": "Revoke API Key", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/api-keys/{{api_key_id}}/revoke", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "api-keys", "{{api_key_id}}", "revoke" ] } }, "response": [] }, { "name": "Rotate API Key", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/api-keys/{{api_key_id}}/rotate", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "api-keys", "{{api_key_id}}", "rotate" ] } }, "response": [] }, { "name": "Create App Key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"mobile-app-key\"\n}" }, "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/app-keys", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "app-keys" ] } }, "response": [] }, { "name": "List App Keys", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/app-keys", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "app-keys" ] } }, "response": [] }, { "name": "Revoke App Key", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/app-keys/{{app_key_id}}/revoke", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "app-keys", "{{app_key_id}}", "revoke" ] } }, "response": [] }, { "name": "Rotate App Key", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/app-keys/{{app_key_id}}/rotate", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "app-keys", "{{app_key_id}}", "rotate" ] } }, "response": [] } ] } ] }, { "name": "Webhook Service", "item": [ { "name": "Create Webhook", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"organization_id\": \"{{organization_id}}\",\n \"name\": \"Primary Endpoint\",\n \"target_url\": \"https://example.com/webhooks/immiblox\"\n}" }, "url": { "raw": "{{webhook_base_url}}/api/v1/webhooks", "host": [ "{{webhook_base_url}}" ], "path": [ "api", "v1", "webhooks" ] } }, "response": [] }, { "name": "List Webhooks", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{webhook_base_url}}/api/v1/webhooks?organization_id={{organization_id}}", "host": [ "{{webhook_base_url}}" ], "path": [ "api", "v1", "webhooks" ], "query": [ { "key": "organization_id", "value": "{{organization_id}}" } ] } }, "response": [] }, { "name": "Delete Webhook", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{webhook_base_url}}/api/v1/webhooks/{{webhook_id}}", "host": [ "{{webhook_base_url}}" ], "path": [ "api", "v1", "webhooks", "{{webhook_id}}" ] } }, "response": [] }, { "name": "List Events", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{webhook_base_url}}/api/v1/events?organization_id={{organization_id}}", "host": [ "{{webhook_base_url}}" ], "path": [ "api", "v1", "events" ], "query": [ { "key": "organization_id", "value": "{{organization_id}}" } ] } }, "response": [] }, { "name": "Create Event", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"organization_id\": \"{{organization_id}}\",\n \"webhook_id\": \"{{webhook_id}}\",\n \"event_type\": \"status.updated\",\n \"payload\": \"{\\\"person_id\\\":\\\"{{person_id}}\\\"}\"\n}" }, "url": { "raw": "{{webhook_base_url}}/api/v1/events", "host": [ "{{webhook_base_url}}" ], "path": [ "api", "v1", "events" ] } }, "response": [] } ] }, { "name": "Production Readiness - Missing Coverage", "item": [ { "name": "Assistant - Delete All Conversations", "request": { "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{assistant_base_url}}/api/v1/conversations/all", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "conversations", "all" ] } }, "response": [] }, { "name": "Assistant - Improve Prompt", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"prompt\": \"Summarize this immigration notice for a dependent visa holder\",\n \"intent\": \"summarization\"\n}" }, "url": { "raw": "{{assistant_base_url}}/api/v1/improve-prompt", "host": [ "{{assistant_base_url}}" ], "path": [ "api", "v1", "improve-prompt" ] } }, "response": [] }, { "name": "Document - Forward Document", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"vault_id\": \"{{vault_id}}\",\n \"document_ids\": [\"{{document_id}}\"],\n \"recipient_emails\": [\"attorney@example.com\"],\n \"message\": \"Forwarding document for legal review\",\n \"sender_name\": \"Immigration Applicant\"\n}" }, "url": { "raw": "{{document_base_url}}/api/v1/documents/forward", "host": [ "{{document_base_url}}" ], "path": [ "api", "v1", "documents", "forward" ] }, "description": "Forward documents to recipients via email. Requires vault_id, document_ids array, and recipient_emails array." }, "response": [] }, { "name": "Organization Machine Auth - Create API Key", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"name\": \"integration-key\",\n \"scopes\": [\"webhook:events:write\", \"immigration:imports:write\"]\n}" }, "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/api-keys", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "api-keys" ] } }, "response": [] }, { "name": "Organization Machine Auth - List API Keys", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{organization_base_url}}/api/v1/organizations/{{organization_id}}/machine-auth/api-keys", "host": [ "{{organization_base_url}}" ], "path": [ "api", "v1", "organizations", "{{organization_id}}", "machine-auth", "api-keys" ] } }, "response": [] }, { "name": "Machine Auth Header Probe - List Webhooks", "request": { "method": "GET", "header": [ { "key": "X-API-Key", "value": "{{api_key}}" }, { "key": "X-App-Key", "value": "{{app_key}}" } ], "url": { "raw": "{{webhook_base_url}}/api/v1/webhooks?organization_id={{organization_id}}", "host": [ "{{webhook_base_url}}" ], "path": [ "api", "v1", "webhooks" ], "query": [ { "key": "organization_id", "value": "{{organization_id}}" } ] } }, "response": [] } ] } ], "variable": [ { "key": "account_base_url", "value": "https://account.api.dev.immiblox.com", "type": "string" }, { "key": "vault_base_url", "value": "https://vault.api.dev.immiblox.com", "type": "string" }, { "key": "document_base_url", "value": "https://document.api.dev.immiblox.com", "type": "string" }, { "key": "embedding_base_url", "value": "https://document.api.dev.immiblox.com", "type": "string" }, { "key": "assistant_base_url", "value": "https://assistant.api.dev.immiblox.com", "type": "string" }, { "key": "workflow_base_url", "value": "https://workflow.api.dev.immiblox.com", "type": "string" }, { "key": "mcp_base_url", "value": "https://mcp.api.dev.immiblox.com", "type": "string" }, { "key": "immigration_base_url", "value": "https://immigration.api.dev.immiblox.com", "type": "string" }, { "key": "organization_base_url", "value": "https://organization.api.dev.immiblox.com", "type": "string" }, { "key": "webhook_base_url", "value": "https://webhook.api.dev.immiblox.com", "type": "string" }, { "key": "google_id_token", "value": "", "type": "string", "description": "Google ID token obtained from Google Sign-In flow. Get this from your frontend application after Google authentication." }, { "key": "web_base_url", "value": "https://app.dev.immiblox.com", "type": "string", "description": "Web app base URL used for OAuth redirect/logout URL parameters." }, { "key": "cognito_auth_code", "value": "", "type": "string", "description": "Authorization code returned by Cognito hosted UI redirect." }, { "key": "share_token", "value": "", "type": "string", "description": "Public share token from vault sharing invitation email. Used for public access endpoints." }, { "key": "execution_id", "value": "", "type": "string", "description": "UUID of the current workflow execution. Set automatically when executing a workflow." }, { "key": "workflow_name", "value": "Translate Document", "type": "string", "description": "Workflow name used by class-based workflow routes." }, { "key": "step_execution_id", "value": "", "type": "string", "description": "UUID of the current step execution. Set automatically when getting execution status." }, { "key": "workflow_execution_id", "value": "", "type": "string", "description": "Alias for execution_id used by legacy workflow requests." }, { "key": "v2_execution_id", "value": "", "type": "string", "description": "UUID of the V2 engine workflow execution. Set automatically when starting a V2 execution." }, { "key": "v2_step_execution_id", "value": "", "type": "string", "description": "UUID of the V2 engine step execution. Set manually or from execution details." }, { "key": "policy_id", "value": "", "type": "string", "description": "ID of a policy for evaluation." }, { "key": "admin_api_key", "value": "", "type": "string", "description": "Admin API key for admin-only endpoints. Set to ADMIN_API_KEY environment variable value." }, { "key": "organization_id", "value": "", "type": "string", "description": "Organization UUID used by organization/immigration/webhook endpoints." }, { "key": "person_id", "value": "", "type": "string", "description": "Person UUID used by immigration endpoints." }, { "key": "status_id", "value": "", "type": "string", "description": "Status UUID used by immigration status endpoints." }, { "key": "member_id", "value": "", "type": "string", "description": "Organization member UUID used for member delete endpoint." }, { "key": "webhook_id", "value": "", "type": "string", "description": "Webhook UUID used for webhook event endpoints." }, { "key": "service_account_id", "value": "", "type": "string", "description": "Service account UUID for organization machine-auth deactivate endpoint." }, { "key": "api_key_id", "value": "", "type": "string", "description": "API key UUID for organization machine-auth revoke/rotate endpoints." }, { "key": "app_key_id", "value": "", "type": "string", "description": "App key UUID for organization machine-auth revoke/rotate endpoints." } ] }