{ "openapi": "3.1.0", "info": { "title": "Case.dev API", "description": "The AI-native platform for legal technology. Build smarter legal applications with our suite of AI-powered APIs.", "version": "1.0.0", "contact": { "name": "Case.dev Support", "email": "support@casemark.com", "url": "https://case.dev" }, "license": { "name": "Proprietary", "url": "https://case.dev/terms" } }, "servers": [ { "url": "https://api.case.dev", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Vaults", "description": "Secure document storage with semantic search" }, { "name": "Vault Events", "description": "Vault-scoped event subscriptions and delivery testing" }, { "name": "Vault Memory", "description": "Vault-scoped persistent memory and semantic retrieval" }, { "name": "Vault Objects", "description": "Vault object management, content access, and document operations" }, { "name": "Memory", "description": "Persistent memory for AI agents with semantic search and 12 generic indexed tag fields" }, { "name": "OCR", "description": "Extract text from PDFs, images, and scanned documents" }, { "name": "Voice", "description": "Audio transcription and text-to-speech" }, { "name": "LLMs", "description": "Access 40+ language models through a unified API" }, { "name": "Search", "description": "Web search and AI answers" }, { "name": "Mail", "description": "Managed inboxes for agent email workflows" }, { "name": "Media", "description": "Transcript retrieval and captioned media clip generation" }, { "name": "Legal", "description": "Legal research tools including citation verification" }, { "name": "Privilege", "description": "Privilege detection for e-discovery and litigation workflows" }, { "name": "Compute", "description": "Serverless GPU and CPU infrastructure" }, { "name": "Format", "description": "Document formatting and template rendering (MD/JSON to PDF/DOCX)" }, { "name": "SuperDoc", "description": "Document conversion and template automation" }, { "name": "Webhooks", "description": "Webhook endpoint management" }, { "name": "System", "description": "Public system metadata and discovery endpoints" }, { "name": "Usage", "description": "Usage reporting and webhook subscriptions" }, { "name": "Database", "description": "Serverless PostgreSQL databases with instant branching" }, { "name": "Translation", "description": "Language detection and translation for multilingual legal workflows" }, { "name": "Skills", "description": "Search and read legal AI skills for agents" }, { "name": "Agents/Linc", "description": "Durable, stateful legal agent sessions with sandboxed tools and files" }, { "name": "Matters", "description": "Matter-native legal workspaces and orchestration primitives" }, { "name": "Connectors", "description": "Import and export between provider folders and vaults" }, { "name": "Applications Projects", "description": "Web application project management" }, { "name": "Applications Deployments", "description": "Web application deployment management" }, { "name": "Applications Domains", "description": "Custom domain configuration for applications" }, { "name": "Applications Env Vars", "description": "Environment variable management for applications" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key starting with `sk_case_`" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "type": { "type": "string" }, "code": { "type": "string" } }, "required": [ "message" ] } } } } }, "paths": { "/compute/v1/environments": { "get": { "tags": [ "Compute" ], "summary": "List environments", "description": "Retrieve all compute environments for your organization. Environments provide isolated execution contexts for running code and workflows.", "operationId": "listEnvironments", "responses": { "200": { "description": "Successfully retrieved environments", "content": { "application/json": { "schema": { "type": "object", "properties": { "environments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique environment identifier" }, "name": { "type": "string", "description": "Human-readable environment name" }, "slug": { "type": "string", "description": "URL-safe environment identifier" }, "domain": { "type": "string", "description": "Environment domain" }, "isDefault": { "type": "boolean", "description": "Whether this is the default environment" }, "status": { "type": "string", "description": "Environment status" }, "createdAt": { "type": "string", "format": "date-time", "description": "Environment creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } } } } }, "example": { "environments": [ { "id": "env_abc123", "name": "Document Review Environment", "slug": "doc-review", "domain": "doc-review.compute.case.dev", "isDefault": true, "status": "active", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T14:45:00Z" }, { "id": "env_def456", "name": "Contract Analysis", "slug": "contract-analysis", "domain": "contract-analysis.compute.case.dev", "isDefault": false, "status": "active", "createdAt": "2024-01-18T09:15:00Z", "updatedAt": "2024-01-18T09:15:00Z" } ] } } } }, "401": { "description": "Authentication required - invalid or missing API key" } }, "x-permissions": [ "compute:read" ] }, "post": { "tags": [ "Compute" ], "summary": "Create compute environment", "description": "Creates a new compute environment for running serverless workloads. Each environment gets its own isolated namespace with a unique domain for hosting applications and APIs. The first environment created becomes the default environment for the organization.", "operationId": "createComputeEnvironment", "responses": { "201": { "description": "Environment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique environment identifier" }, "name": { "type": "string", "description": "Environment name" }, "slug": { "type": "string", "description": "URL-friendly slug derived from name" }, "domain": { "type": "string", "description": "Unique domain for this environment" }, "isDefault": { "type": "boolean", "description": "Whether this is the default environment" }, "status": { "type": "string", "description": "Environment status", "enum": [ "active", "inactive" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Environment creation timestamp" } } }, "example": { "id": "env_abc123", "name": "document-review-prod", "slug": "document-review-prod", "domain": "document-review-prod-lawfirm.case.dev", "isDefault": true, "status": "active", "createdAt": "2024-01-15T10:30:00Z" } } } }, "400": { "description": "Invalid request - missing name or invalid name format" }, "401": { "description": "Invalid API key" }, "404": { "description": "Organization not found" }, "409": { "description": "Environment with this name already exists" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Environment name (alphanumeric, hyphens, and underscores only)", "pattern": "^[a-zA-Z0-9_-]+$", "example": "document-review-prod" } } } } } }, "x-permissions": [ "compute:environments:create" ] } }, "/compute/v1/environments/{name}": { "get": { "tags": [ "Compute" ], "summary": "Get compute environment", "description": "Retrieve a specific compute environment by name. Returns environment configuration including status, domain, and metadata for your serverless compute infrastructure.", "operationId": "getComputeEnvironment", "responses": { "200": { "description": "Environment retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique environment identifier" }, "name": { "type": "string", "description": "Environment name" }, "slug": { "type": "string", "description": "URL-safe environment slug" }, "domain": { "type": "string", "description": "Environment domain URL" }, "isDefault": { "type": "boolean", "description": "Whether this is the default environment" }, "status": { "type": "string", "description": "Environment status (active, inactive, etc.)" }, "createdAt": { "type": "string", "format": "date-time", "description": "Environment creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Environment last update timestamp" } } }, "example": { "id": "env_12345", "name": "production-legal-docs", "slug": "production-legal-docs", "domain": "https://prod-legal.case.dev", "isDefault": true, "status": "active", "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T10:45:00Z" } } } }, "400": { "description": "Bad request - Environment name is required" }, "401": { "description": "Unauthorized - Invalid API key" }, "404": { "description": "Environment not found" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The name of the compute environment to retrieve" } ], "x-permissions": [ "compute:read" ] }, "delete": { "tags": [ "Compute" ], "summary": "Delete compute environment", "description": "Permanently delete a compute environment and all its associated resources. This will stop all running deployments and clean up related configurations. The default environment cannot be deleted if other environments exist.", "operationId": "deleteComputeEnvironment", "responses": { "200": { "description": "Environment deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Environment 'litigation-processing' deleted" } }, "required": [ "success", "message" ] } } } }, "400": { "description": "Bad request - Environment name missing or cannot delete default environment" }, "401": { "description": "Unauthorized - Invalid API key" }, "404": { "description": "Environment not found" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the compute environment to delete", "example": "litigation-processing" } ], "x-permissions": [ "compute:environments:delete" ] } }, "/compute/v1/environments/{name}/default": { "post": { "tags": [ "Compute" ], "summary": "Set default environment", "description": "Sets a compute environment as the default for the organization. Only one environment can be default at a time - setting a new default will automatically unset the previous one.", "operationId": "setDefaultComputeEnvironment", "responses": { "200": { "description": "Environment successfully set as default", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique environment identifier" }, "name": { "type": "string", "description": "Environment name" }, "slug": { "type": "string", "description": "URL-friendly environment identifier" }, "domain": { "type": "string", "description": "Environment domain" }, "isDefault": { "type": "boolean", "description": "Whether this is the default environment" }, "status": { "type": "string", "description": "Current environment status" }, "createdAt": { "type": "string", "format": "date-time", "description": "Environment creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "example": { "id": "env_123abc", "name": "prod-legal-docs", "slug": "prod-legal-docs", "domain": "prod-legal-docs.case.dev", "isDefault": true, "status": "active", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T14:30:00Z" } } } }, "400": { "description": "Environment name is required" }, "401": { "description": "Invalid API key" }, "404": { "description": "Environment not found" } }, "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the compute environment to set as default", "example": "prod-legal-docs" } ], "x-permissions": [ "compute:write" ] } }, "/compute/v1/health": { "get": { "tags": [ "Compute" ], "summary": "Health check", "description": "Unauthenticated health check for the Compute service.", "operationId": "getComputeHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "compute" } } } } } } }, "/compute/v1/instance-types": { "get": { "tags": [ "Compute" ], "summary": "List GPU instance types", "description": "Retrieves all available GPU instance types with pricing, specifications, and regional availability. Includes T4, A10, A100, H100, and H200 GPUs powered by Lambda Labs. Perfect for AI model training, inference workloads, and legal document OCR processing at scale.", "operationId": "listGpuInstanceTypes", "responses": { "200": { "description": "Instance types retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "instanceTypes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Instance type identifier" }, "description": { "type": "string", "description": "Instance description" }, "gpu": { "type": "string", "description": "GPU model and count" }, "pricePerHour": { "type": "string", "description": "Price per hour (e.g. '$1.20')" }, "specs": { "type": "object", "properties": { "vcpus": { "type": "integer", "description": "Number of vCPUs" }, "memoryGib": { "type": "integer", "description": "RAM in GiB" }, "storageGib": { "type": "integer", "description": "Storage in GiB" } } }, "regionsAvailable": { "type": "array", "items": { "type": "string" }, "description": "Available regions" } } } }, "count": { "type": "integer", "description": "Total number of instance types" } }, "required": [ "instanceTypes", "count" ] }, "example": { "instanceTypes": [ { "name": "gpu_1x_a10", "description": "1x NVIDIA A10 GPU", "gpu": "1x A10 (24 GB)", "pricePerHour": "$0.60", "specs": { "vcpus": 30, "memoryGib": 200, "storageGib": 1400 }, "regionsAvailable": [ "us-west-1", "us-east-1" ] } ], "count": 12 } } } }, "401": { "description": "Invalid or missing API key" }, "500": { "description": "Failed to list instance types" } }, "x-permissions": [ "compute:read" ] } }, "/compute/v1/instances": { "get": { "tags": [ "Compute" ], "summary": "List GPU instances", "description": "Retrieves all GPU compute instances for your organization with real-time status updates from Lambda Labs. Includes pricing and runtime metrics. Perfect for monitoring AI workloads, document processing jobs, and cost tracking.", "operationId": "listGpuInstances", "responses": { "200": { "description": "Instances retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "instances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "booting", "running", "stopping", "stopped", "terminated", "failed" ] }, "ip": { "type": "string", "nullable": true }, "instanceType": { "type": "string" }, "region": { "type": "string" }, "pricePerHour": { "type": "string" }, "gpu": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "totalRuntimeSeconds": { "type": "integer" }, "totalCost": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" } } }, "example": { "instances": [ { "id": "gpu_abc123", "name": "ocr-processing", "status": "running", "ip": "143.198.54.123", "instanceType": "gpu_1x_a10", "region": "us-west-1", "pricePerHour": "$0.60", "gpu": "1x A10 (24 GB)", "startedAt": "2025-01-15T10:00:00Z", "totalRuntimeSeconds": 1800, "totalCost": "$0.30", "createdAt": "2025-01-15T10:00:00Z" } ], "count": 1 } } } }, "401": { "description": "Invalid or missing API key" }, "500": { "description": "Failed to list instances" } }, "x-permissions": [ "compute:read" ] }, "post": { "tags": [ "Compute" ], "summary": "Launch GPU instance", "description": "Launches a new GPU compute instance with automatic SSH key generation. Supports mounting Case.dev Vaults as filesystems. Instance boots in ~2-5 minutes. Perfect for batch OCR processing, AI model training, and intensive document analysis workloads.", "operationId": "launchGpuInstance", "responses": { "201": { "description": "Instance launching", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "instanceType": { "type": "string" }, "region": { "type": "string" }, "pricePerHour": { "type": "string" }, "gpu": { "type": "string" }, "specs": { "type": "object" }, "vaults": { "type": "array" }, "createdAt": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid parameters" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Instance type, region, or vault not found" }, "409": { "description": "Instance with this name already exists" }, "500": { "description": "Failed to launch instance" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Instance name" }, "instanceType": { "type": "string", "description": "GPU type (e.g., 'gpu_1x_h100_sxm5')" }, "region": { "type": "string", "description": "Region (e.g., 'us-west-1')" }, "vaultIds": { "type": "array", "items": { "type": "string" }, "description": "Vault IDs to mount" } }, "required": [ "name", "instanceType", "region" ] }, "example": { "name": "ocr-batch-job", "instanceType": "gpu_1x_a10", "region": "us-west-1", "vaultIds": [ "vault_abc123" ] } } } }, "x-permissions": [ "compute:write" ] } }, "/compute/v1/instances/{id}": { "get": { "tags": [ "Compute" ], "summary": "Get GPU instance", "description": "Retrieves detailed information about a GPU instance including SSH connection details, vault mount scripts, real-time cost tracking, and current status. SSH private key included for secure access.", "operationId": "getGpuInstance", "responses": { "200": { "description": "Instance details retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "ip": { "type": "string", "nullable": true }, "instanceType": { "type": "string" }, "region": { "type": "string" }, "pricePerHour": { "type": "string" }, "gpu": { "type": "string" }, "specs": { "type": "object" }, "startedAt": { "type": "string", "nullable": true }, "currentRuntimeSeconds": { "type": "integer" }, "currentCost": { "type": "string" }, "createdAt": { "type": "string" }, "ssh": { "type": "object", "nullable": true, "properties": { "host": { "type": "string" }, "user": { "type": "string" }, "command": { "type": "string" }, "privateKey": { "type": "string" }, "instructions": { "type": "array" } } }, "vaultMounts": { "type": "object", "nullable": true } } } } } }, "400": { "description": "Invalid instance ID" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Instance not found" }, "500": { "description": "Failed to get instance" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Instance ID" } ], "x-permissions": [ "compute:read" ] }, "delete": { "tags": [ "Compute" ], "summary": "Terminate GPU instance", "description": "Terminates a running GPU instance, calculates final cost, and cleans up SSH keys. This action is permanent and cannot be undone. All data on the instance will be lost.", "operationId": "terminateGpuInstance", "responses": { "200": { "description": "Instance terminated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "totalRuntimeSeconds": { "type": "integer" }, "totalCost": { "type": "string" }, "message": { "type": "string" } } }, "example": { "id": "gpu_abc123", "name": "ocr-processing", "status": "terminated", "totalRuntimeSeconds": 3600, "totalCost": "$0.60", "message": "Instance terminated successfully" } } } }, "400": { "description": "Instance already terminated or invalid ID" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Instance not found" }, "500": { "description": "Failed to terminate instance" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Instance ID to terminate" } ], "x-permissions": [ "compute:write" ] } }, "/compute/v1/pricing": { "get": { "tags": [ "Compute" ], "summary": "Get compute pricing information", "description": "Returns current pricing for GPU instances. Prices are fetched in real-time and include a 20% platform fee. For detailed instance types and availability, use GET /compute/v1/instance-types.", "operationId": "getComputePricing", "responses": { "200": { "description": "Compute pricing information" } } } }, "/compute/v1/secrets": { "get": { "tags": [ "Compute" ], "summary": "List secret groups", "description": "Retrieve all secret groups for a compute environment. Secret groups organize related secrets (API keys, credentials, etc.) that can be securely accessed by compute jobs during execution.", "operationId": "listSecretGroups", "responses": { "200": { "description": "Successfully retrieved secret groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the secret group" }, "name": { "type": "string", "description": "Name of the secret group" }, "description": { "type": "string", "description": "Description of the secret group" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the secret group was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the secret group was last updated" } } } } } }, "example": { "groups": [ { "id": "sg_abc123", "name": "legal-apis", "description": "API keys for legal research services", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" }, { "id": "sg_def456", "name": "database-creds", "description": "Database connection credentials", "createdAt": "2024-01-10T14:20:00Z", "updatedAt": "2024-01-12T09:15:00Z" } ] } } } }, "400": { "description": "No environment specified and no default environment found" }, "401": { "description": "Invalid API key" }, "404": { "description": "Specified environment not found" } }, "parameters": [ { "name": "env", "in": "query", "description": "Environment name to list secret groups for. If not specified, uses the default environment.", "required": false, "schema": { "type": "string" }, "example": "production" } ], "x-permissions": [ "compute:read" ] }, "post": { "tags": [ "Compute" ], "summary": "Create secret group", "description": "Creates a new secret group in a compute environment. Secret groups organize related secrets for use in serverless functions and workflows. If no environment is specified, the group is created in the default environment.\n\n**Features:**\n- Organize secrets by logical groups (e.g., database, APIs, third-party services)\n- Environment-based isolation\n- Validation of group names\n- Conflict detection for existing groups", "operationId": "createSecretGroup", "responses": { "201": { "description": "Secret group created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the secret group" }, "name": { "type": "string", "description": "Name of the secret group" }, "description": { "type": "string", "description": "Description of the secret group" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp" } } }, "example": { "id": "sg_abc123def456", "name": "database-credentials", "description": "Database connection secrets for case management system", "createdAt": "2024-01-15T10:30:00Z" } } } }, "400": { "description": "Bad request - invalid parameters or missing required fields" }, "401": { "description": "Unauthorized - invalid API key" }, "404": { "description": "Environment not found" }, "409": { "description": "Conflict - secret group with this name already exists in the environment" } }, "requestBody": { "description": "Secret group configuration", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "description": "Unique name for the secret group. Must contain only letters, numbers, hyphens, and underscores." }, "description": { "type": "string", "description": "Optional description of the secret group's purpose" }, "env": { "type": "string", "description": "Environment name where the secret group will be created. Uses default environment if not specified." } } } } } }, "x-permissions": [ "compute:secrets:write" ] } }, "/compute/v1/secrets/{group}": { "get": { "tags": [ "Compute" ], "summary": "List secret keys in a group", "description": "Retrieve the keys (names) of secrets in a specified group within a compute environment. For security reasons, actual secret values are not returned - only the keys and metadata.", "operationId": "listSecretKeys", "responses": { "200": { "description": "Secret keys retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the secret group" }, "name": { "type": "string", "description": "Name of the secret group" }, "description": { "type": "string", "description": "Description of the secret group" } } }, "keys": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Name of the secret key" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the secret was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the secret was last updated" } } } } } }, "example": { "group": { "id": "grp_123", "name": "api-keys", "description": "Third-party API keys for legal research tools" }, "keys": [ { "key": "LEXIS_API_KEY", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" }, { "key": "WESTLAW_ACCESS_TOKEN", "createdAt": "2024-01-16T14:20:00Z", "updatedAt": "2024-01-20T09:15:00Z" } ] } } } }, "400": { "description": "Invalid request - missing group name or no default environment found" }, "401": { "description": "Authentication failed - invalid or missing API key" }, "404": { "description": "Secret group or environment not found" } }, "parameters": [ { "name": "group", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the secret group to list keys from" }, { "name": "env", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Environment name. If not specified, uses the default environment" } ], "x-permissions": [ "compute:secrets:read" ] }, "put": { "tags": [ "Compute" ], "summary": "Set secrets in group", "description": "Set or update secrets in a compute secret group. Secrets are encrypted with AES-256-GCM. Use this to manage environment variables and API keys for your compute workloads.", "operationId": "setComputeSecrets", "responses": { "200": { "description": "Secrets successfully set", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "group": { "type": "string", "description": "Name of the secret group" }, "created": { "type": "number", "description": "Number of new secrets created" }, "updated": { "type": "number", "description": "Number of existing secrets updated" }, "message": { "type": "string" } } }, "example": { "success": true, "group": "litigation-apis", "created": 2, "updated": 1, "message": "Secrets saved" } } } }, "400": { "description": "Invalid request - missing secrets, invalid key format, or no environment found" }, "401": { "description": "Invalid API key" }, "404": { "description": "Specified environment not found" } }, "parameters": [ { "name": "group", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the secret group", "example": "litigation-apis" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "object", "description": "Key-value pairs of secrets to set", "additionalProperties": { "type": "string" } }, "env": { "type": "string", "description": "Environment name (optional, uses default if not specified)" } } } } } }, "x-permissions": [ "compute:secrets:write" ] }, "delete": { "tags": [ "Compute" ], "summary": "Delete secret group or key", "description": "Delete an entire secret group or a specific key within a secret group. When deleting a specific key, the remaining secrets in the group are preserved. When deleting the entire group, all secrets and the group itself are removed.", "operationId": "deleteSecret", "responses": { "200": { "description": "Secret or secret group successfully deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "example": { "success": true, "message": "Deleted key 'DATABASE_PASSWORD' from group 'database-config'" } } } }, "400": { "description": "Bad request - missing group name or no default environment" }, "401": { "description": "Unauthorized - invalid API key" }, "404": { "description": "Secret group, environment, or organization not found" } }, "parameters": [ { "name": "group", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Name of the secret group" }, { "name": "key", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Specific key to delete within the group. If not provided, the entire group is deleted" }, { "name": "env", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Environment name. If not provided, uses the default environment" } ], "x-permissions": [ "compute:secrets:delete" ] } }, "/compute/v1/usage": { "get": { "tags": [ "Compute" ], "summary": "Get compute usage and billing", "description": "Returns detailed compute usage statistics and billing information for your organization. Includes GPU and CPU hours, total runs, costs, and breakdowns by environment. Use optional query parameters to filter by specific year and month.", "operationId": "getComputeUsage", "responses": { "200": { "description": "Usage statistics and billing information", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" }, "monthName": { "type": "string" } } }, "summary": { "type": "object", "properties": { "totalRuns": { "type": "integer" }, "totalGpuHours": { "type": "number" }, "totalCpuHours": { "type": "number" }, "totalCostCents": { "type": "integer" }, "totalCostFormatted": { "type": "string" } } }, "byEnvironment": { "type": "array", "items": { "type": "object", "properties": { "environment": { "type": "string" }, "totalRuns": { "type": "integer" }, "totalGpuSeconds": { "type": "integer" }, "totalCpuSeconds": { "type": "integer" }, "totalCostCents": { "type": "integer" }, "totalCostFormatted": { "type": "string" } } } } } }, "example": { "period": { "year": 2024, "month": 3, "monthName": "March" }, "summary": { "totalRuns": 47, "totalGpuHours": 12.5, "totalCpuHours": 3.2, "totalCostCents": 4750, "totalCostFormatted": "$47.50" }, "byEnvironment": [ { "environment": "legal-document-processing", "totalRuns": 35, "totalGpuSeconds": 36000, "totalCpuSeconds": 7200, "totalCostCents": 3200, "totalCostFormatted": "$32.00" }, { "environment": "contract-analysis", "totalRuns": 12, "totalGpuSeconds": 9000, "totalCpuSeconds": 4320, "totalCostCents": 1550, "totalCostFormatted": "$15.50" } ] } } } }, "401": { "description": "Unauthorized - Valid API key required" } }, "parameters": [ { "name": "year", "in": "query", "description": "Year to filter usage data (defaults to current year)", "required": false, "schema": { "type": "integer", "example": 2024 } }, { "name": "month", "in": "query", "description": "Month to filter usage data (1-12, defaults to current month)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 12, "example": 3 } } ], "x-permissions": [ "compute:read" ] } }, "/connectors/v1/applications/{id}/keys/{keyId}": { "put": { "tags": [ "Connectors" ], "summary": "Bind an application management key", "description": "Requires an owner/admin Clerk session. Explicitly binds a non-system connector API key to one application. Allows multiple keys for controlled rotation. Does not grant Vault access or mint credentials.", "operationId": "bindConnectorApplicationKey", "responses": { "200": { "description": "Binding established", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "application_id", "api_key_id" ], "properties": { "id": { "type": "string" }, "application_id": { "type": "string" }, "api_key_id": { "type": "string" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Admin session required" }, "404": { "description": "Application or key not found" }, "409": { "description": "Key belongs to another application" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] }, "delete": { "tags": [ "Connectors" ], "summary": "Revoke an application management key binding", "description": "Requires an owner/admin Clerk session. Immediately invalidates tokens minted through this binding. Rebinding later does not revive those tokens.", "operationId": "revokeConnectorApplicationKey", "responses": { "204": { "description": "Binding revoked" }, "401": { "description": "Authentication required" }, "403": { "description": "Admin session required" }, "404": { "description": "Application or key not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/connections": { "get": { "tags": [ "Connectors" ], "summary": "List connections", "description": "List provider connections for the organization, with health status. Returns at most `limit` connections (default 200, maximum 200). When `pagination.has_more` is true, replay `pagination.next_cursor` as `?cursor=` to fetch the following page. Cursors are opaque and are only valid for the exact filter set and installation/subject scope they were issued under.", "operationId": "listConnectorConnections", "responses": { "200": { "description": "Connections for the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "type": "object", "properties": { "organization_id": { "type": "string", "description": "Authenticated organization owning this connection; server-side approval binding uses this identifier." } }, "additionalProperties": true } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "cursor": { "type": "string", "nullable": true, "deprecated": true, "description": "Mirror of `pagination.next_cursor`. Prefer `pagination`." }, "providers": { "type": "array", "description": "Available import providers and their adapter-declared capabilities.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scope_tier": { "type": "string" }, "browse_scope_tiers": { "type": "array", "items": { "type": "string" }, "description": "Exact enabled tiers accepted by the adapter browse policy." }, "authorization_options": { "type": "array", "items": { "type": "object", "properties": { "scope_tier": { "type": "string" }, "label": { "type": "string" }, "write_scope_tier": { "type": "string", "nullable": true, "description": "Explicit write-authorization upgrade for this account choice. Null means unavailable by policy; omitted when no upgrade is required." } } }, "description": "Adapter-declared consent choices, filtered by deployment and organization policy." }, "supports_export": { "type": "boolean" }, "resource_types": { "type": "array", "items": { "type": "string" } }, "search": { "type": "object", "nullable": true, "description": "Present when GET /connections/{id}/search works for this provider.", "properties": { "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account", "folder" ] } }, "full_text": { "type": "boolean" }, "folder_scope_recursive": { "type": "boolean" }, "max_page_size": { "type": "integer" } } } } } }, "capabilities": { "type": "object", "properties": { "google_drive_folder_mirroring": { "type": "boolean" } } } } } } } }, "400": { "description": "Invalid cursor or limit" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "provider", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "healthy", "reauth_required", "revoked", "throttled" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Connections per page (1-200). Defaults to 200." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor from `pagination.next_cursor` of the previous page. Must be replayed with the same filters and scope that produced it." } ], "x-permissions": [ "connectors" ] }, "post": { "tags": [ "Connectors" ], "summary": "Create connection", "description": "Create a pending provider connection and return a one-time connect_url for the hosted OAuth flow. The user completes provider consent at connect_url and is redirected to return_url with ?connection_id=.", "operationId": "createConnectorConnection", "responses": { "201": { "description": "Pending connection created", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string" }, "connect_url": { "type": "string" }, "expires_at": { "type": "string" } } } } } }, "400": { "description": "Unknown provider or invalid return_url" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "503": { "description": "Provider unavailable in this environment" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "return_url" ], "properties": { "provider": { "type": "string", "enum": [ "box", "clio", "dropbox", "gdrive", "microsoft", "smokeball" ] }, "return_url": { "type": "string", "description": "HTTPS URL the user is sent back to after consent." }, "scope_tier": { "type": "string", "enum": [ "box.readwrite", "box.readwrite.webhooks", "clio.us", "dropbox.readwrite", "drive", "microsoft.account.read", "microsoft.read", "microsoft.personal.read", "microsoft.write", "microsoft.personal.write", "smokeball.us", "smokeball.us.staging", "smokeball.us.staging.write", "smokeball.us.write" ], "description": "Provider-specific OAuth permission tier. Omit to use the provider's default. Use microsoft.account.read to let Microsoft choose a personal or work/school account. Existing explicit microsoft.read and microsoft.personal.read tiers remain supported. Microsoft write tiers require the separate write switch and explicit authorization for bounded exports and paired sync." } } } } } }, "x-permissions": [ "connectors" ] }, "patch": { "tags": [ "Connectors" ], "summary": "Update provider availability", "description": "Enable or disable new runs and scheduled syncs for one provider across the authenticated organization or installation. This organization-wide operation requires explicit confirmation. Existing credentials, links, and imported files are preserved; active runs are not interrupted.", "operationId": "updateConnectorProviderAvailability", "responses": { "200": { "description": "Provider availability updated" }, "400": { "description": "Invalid provider, body, or user-scoped request" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "enabled", "confirm_organization_wide" ], "properties": { "provider": { "type": "string" }, "enabled": { "type": "boolean" }, "confirm_organization_wide": { "type": "boolean", "enum": [ true ], "description": "Confirms that this change applies to every user connection in scope." } } } } } }, "x-permissions": [ "connectors" ] } }, "/connectors/v1/connections/{id}": { "get": { "tags": [ "Connectors" ], "summary": "Get connection", "description": "Retrieve one provider connection, including account identity and health.", "operationId": "getConnectorConnection", "responses": { "200": { "description": "Connection detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": "string", "description": "Authenticated organization owning this connection; server-side approval binding uses this identifier." } }, "additionalProperties": true } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Connection not found" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] }, "delete": { "tags": [ "Connectors" ], "summary": "Delete connection", "description": "Unlink a provider account: revoke tokens at the provider and delete them. purge=true additionally deletes the vault documents its import links brought in.", "operationId": "deleteConnectorConnection", "responses": { "202": { "description": "Connection revoked; imported-document purge scheduled" }, "204": { "description": "Connection revoked and tokens deleted" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Connection not found" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "purge", "in": "query", "schema": { "type": "boolean", "default": false } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/connections/{id}/browse": { "get": { "tags": [ "Connectors" ], "summary": "Browse remote folders", "description": "Browse the provider one level at a time. Without a site, container, or parent, returns top-level resources. Pass the stable browse_ref fields returned by one response to navigate into the next level. Returns 403 provider_scope_insufficient when the connection scope cannot browse server-side. Clio browsing shares request capacity with background runs; throttled responses include Retry-After when a retry deadline is known.", "operationId": "browseConnectorConnection", "responses": { "200": { "description": "One browse level", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "kind": { "type": "string", "enum": [ "my_drive", "shared_drive", "matter", "site", "document_library", "folder", "file" ] }, "mime_type": { "type": "string", "nullable": true }, "size_bytes": { "type": "integer", "nullable": true }, "modified_at": { "type": "string", "nullable": true }, "path": { "type": "string", "nullable": true }, "container_id": { "type": "string", "nullable": true }, "parent_ids": { "type": "array", "items": { "type": "string" } }, "browse_ref": { "type": "object", "nullable": true }, "import_ref": { "type": "object", "nullable": true, "description": "Importable container root, when different from its browse reference." }, "open_ref": { "type": "string", "nullable": true, "description": "Signed reference to this file for POST /connectors/v1/fetch. Null for folders and providers without single-file fetch. Pass it back exactly as received." } } } }, "cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Unsupported browse level or invalid query parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions or provider_scope_insufficient" }, "404": { "description": "Connection or folder not found" }, "409": { "description": "Connection is not healthy (reauth required)" }, "429": { "description": "Provider request budget exhausted; Retry-After specifies seconds to wait when known", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying" } } } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "site", "in": "query", "schema": { "type": "string" }, "description": "Site id to list" }, { "name": "parent", "in": "query", "schema": { "type": "string" }, "description": "Folder id to list" }, { "name": "container", "in": "query", "schema": { "type": "string" }, "description": "Container id to list, or the container containing parent" }, { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Optional provider-supported search text" }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "maximum": 1000 } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/connections/{id}/microsoft-admin-approval": { "post": { "tags": [ "Connectors" ], "summary": "Prepare Microsoft IT approval", "description": "Create a seven-day, replaceable IT approval link for a pending Microsoft connection. Approval does not connect an account. Only delegated document read scopes are requested.", "operationId": "createMicrosoftAdminApproval", "responses": { "200": { "description": "Approval URL and expiry", "content": { "application/json": { "schema": { "type": "object", "required": [ "approval_url", "expires_at" ], "properties": { "approval_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Insufficient access" }, "404": { "description": "Pending Microsoft connection not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string" }, "description": "Trusted application-user assertion derived from the authenticated application session." } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/connections/{id}/search": { "get": { "tags": [ "Connectors" ], "summary": "Search remote files", "description": "Search the provider's files by name, and by content where the provider supports it. Without a scope, searches everything the connection can see; pass the browse_ref fields of a folder or container to search inside it. Each response states whether its folder scope covers the whole subtree. Returns 422 search_not_supported when the provider has no search, and shares the provider request budget with browsing and background runs.", "operationId": "searchConnectorConnection", "responses": { "200": { "description": "One page of matching files", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "file" ] }, "mime_type": { "type": "string", "nullable": true }, "size_bytes": { "type": "integer", "nullable": true }, "modified_at": { "type": "string", "nullable": true }, "path": { "type": "string", "nullable": true }, "container_id": { "type": "string", "nullable": true }, "parent_ids": { "type": "array", "items": { "type": "string" } }, "unsupported_reason": { "type": "string", "nullable": true, "description": "Set when the file cannot be imported (for example a Box note)" }, "open_ref": { "type": "string", "nullable": true, "description": "Signed reference to this file for POST /connectors/v1/fetch. Null for providers without single-file fetch. Pass it back exactly as received." } } } }, "cursor": { "type": "string", "nullable": true }, "scope": { "type": "string", "enum": [ "account", "folder" ] }, "scope_ref": { "type": "object", "nullable": true }, "full_text": { "type": "boolean", "description": "Whether the provider matches file contents, not only names" }, "folder_scope_recursive": { "type": "boolean", "description": "False when a folder scope covers its direct children only" } } } } } }, "400": { "description": "Missing query or unsupported scope reference" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions or provider_scope_insufficient" }, "404": { "description": "Connection or folder not found" }, "409": { "description": "Connection is not healthy (reauth required)" }, "422": { "description": "search_not_supported or search_scope_not_supported" }, "429": { "description": "Provider request budget exhausted; Retry-After specifies seconds to wait when known", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying" } } } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 256 }, "description": "Search text" }, { "name": "site", "in": "query", "schema": { "type": "string" }, "description": "Site to search in" }, { "name": "container", "in": "query", "schema": { "type": "string" }, "description": "Container to search in, or the container holding parent" }, { "name": "parent", "in": "query", "schema": { "type": "string" }, "description": "Folder to search in" }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "maximum": 1000 } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/fetch": { "post": { "tags": [ "Connectors" ], "summary": "Fetch one remote file", "description": "Copy one provider file, named by an open_ref from browse, into a Vault (vault_id) or to a presigned S3 PUT URL (upload_url). Runs synchronously; files over 100 MB return 413 and belong in a transfer. A repeat for an unchanged provider version returns the first copy with 200. Vault copies are stored as uploaded: call POST /vault/{id}/ingest/{objectId} to index them. Fetched copies are never exported by a link.", "operationId": "fetchConnectorFile", "responses": { "200": { "description": "An earlier copy of this provider version, returned without downloading" }, "201": { "description": "File copied", "content": { "application/json": { "schema": { "type": "object", "properties": { "fetch_id": { "type": "string" }, "reused": { "type": "boolean", "description": "True when an earlier copy was returned" }, "vault_id": { "type": "string", "nullable": true }, "vault_object_id": { "type": "string", "nullable": true }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "checksum": { "type": "string", "description": "sha256 of the copied bytes" }, "provider_version": { "type": "object", "nullable": true }, "modified_at": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Missing open_ref, or not exactly one valid destination" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions, Vault not granted, or connector disabled" }, "404": { "description": "open_ref, connection, Vault or file not found" }, "409": { "description": "Connection needs reauthorization, or fetch_in_progress" }, "413": { "description": "fetch_too_large: over 100 MB" }, "422": { "description": "fetch_not_supported or fetch_unsupported_item" }, "429": { "description": "Provider request budget exhausted; Retry-After when known", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds before retrying" } } }, "502": { "description": "provider_error or upload_url_rejected" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Must match the subject the open_ref was minted for." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "open_ref" ], "properties": { "open_ref": { "type": "string", "description": "From a browse item, exactly as received" }, "vault_id": { "type": "string", "description": "Destination Vault. Exactly one destination." }, "upload_url": { "type": "string", "description": "Presigned HTTPS S3 PUT URL. Content-Type must not be a signed header. Exactly one destination." } } } } } }, "x-permissions": [ "connectors" ] } }, "/connectors/v1/health": { "get": { "tags": [ "Connectors" ], "summary": "Health check", "description": "Unauthenticated health check for the Connectors service.", "operationId": "getConnectorsHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "providers": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "connectors", "providers": [ "box", "clio", "dropbox", "gdrive", "microsoft", "smokeball" ] } } } } } } }, "/connectors/v1/installations": { "get": { "tags": [ "Connectors" ], "summary": "List installations", "description": "List application installations (tenants) in this organization. Returns at most `limit` installations (default 200, maximum 200). When `pagination.has_more` is true, replay `pagination.next_cursor` as `?cursor=` to fetch the following page. Cursors are opaque and are only valid for the exact filter set and caller scope they were issued under.", "operationId": "listConnectorInstallations", "responses": { "200": { "description": "Installations for the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "installations": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "Invalid cursor or limit" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" } }, "parameters": [ { "name": "application", "in": "query", "schema": { "type": "string" } }, { "name": "external_tenant_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Installations per page (1-200). Defaults to 200." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor from `pagination.next_cursor` of the previous page. Must be replayed with the same filters and scope that produced it." } ], "x-permissions": [ "connectors" ] }, "post": { "tags": [ "Connectors" ], "summary": "Ensure installation", "description": "Idempotently create (or return) the installation for (application, external_tenant_id) in this organization. Send the returned installation id as X-Case-Installation-Id on connector requests to scope them to this tenant.", "operationId": "ensureConnectorInstallation", "responses": { "200": { "description": "Existing installation returned" }, "201": { "description": "Installation created" }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions or installation unavailable to this credential" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "application", "external_tenant_id" ], "properties": { "application": { "type": "string", "description": "Consuming application key (e.g. \"p3\")." }, "external_tenant_id": { "type": "string", "description": "The application's own tenant identifier (e.g. a P3 organization id)." } } } } } }, "x-permissions": [ "connectors" ] } }, "/connectors/v1/installations/{id}/tokens": { "post": { "tags": [ "Connectors" ], "summary": "Mint an installation credential", "description": "Bound application management API key only. Returns a 256-bit opaque bearer secret once; valid for 15 minutes, connector data-plane only. No refresh token. At most 4 overlapping credentials and 20 mints/minute per installation. The application server must derive tenant identity; this is not browser authentication.", "operationId": "createConnectorInstallationToken", "responses": { "201": { "description": "Credential minted; never put it in a URL or log", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "token", "expires_at", "installation_id" ], "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "installation_id": { "type": "string" } } } } } }, "400": { "description": "Invalid scopes" }, "401": { "description": "Invalid credential" }, "403": { "description": "Active application management key required" }, "404": { "description": "Installation not found" }, "429": { "description": "Issuance limit reached" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scopes" ], "additionalProperties": false, "properties": { "scopes": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "type": "string", "enum": [ "read", "write" ] } } } } } } }, "x-permissions": [ "connectors" ] } }, "/connectors/v1/installations/{id}/tokens/{tokenId}": { "delete": { "tags": [ "Connectors" ], "summary": "Revoke an installation credential", "description": "Issuing API key only; installation credentials cannot revoke or mint credentials. Immediate revocation on the next request.", "operationId": "revokeConnectorInstallationToken", "responses": { "204": { "description": "Credential revoked" }, "401": { "description": "Invalid credential" }, "403": { "description": "Issuing application key required" }, "404": { "description": "Credential not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/installations/{id}/vaults": { "get": { "tags": [ "Connectors" ], "summary": "List installation vault grants", "description": "List the vaults an installation may use, with capabilities and revocation state.", "operationId": "listConnectorInstallationVaultGrants", "responses": { "200": { "description": "Grants for the installation" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Installation not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/installations/{id}/vaults/{vaultId}": { "put": { "tags": [ "Connectors" ], "summary": "Upsert installation vault grant", "description": "Grant (or update) an installation's access to a vault. Re-granting a revoked vault reactivates it. Import links need can_write; export links need can_read; mirror deletion and purge need can_manage.", "operationId": "upsertConnectorInstallationVaultGrant", "responses": { "200": { "description": "Grant upserted" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Installation or vault not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "relationship": { "type": "string", "enum": [ "owned", "shared" ], "default": "owned" }, "can_read": { "type": "boolean", "default": true }, "can_write": { "type": "boolean", "default": true }, "can_manage": { "type": "boolean", "default": false }, "source": { "type": "string", "enum": [ "provisioning", "lazy_reconcile", "explicit_share" ], "default": "lazy_reconcile" } } } } } }, "x-permissions": [ "connectors" ] }, "delete": { "tags": [ "Connectors" ], "summary": "Revoke installation vault grant", "description": "Revoke an installation's access to a vault. Links using the vault pause at their next run; nothing is deleted.", "operationId": "revokeConnectorInstallationVaultGrant", "responses": { "204": { "description": "Grant revoked" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Installation or active grant not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "vaultId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/links": { "get": { "tags": [ "Connectors" ], "summary": "List links", "description": "List transfer links, filterable by vault, connection, direction, mode, and state.", "operationId": "listConnectorLinks", "responses": { "200": { "description": "Links for the organization" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "vault_id", "in": "query", "schema": { "type": "string" } }, { "name": "connection_id", "in": "query", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "import", "export" ] } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "once", "synced" ] } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "ready", "running", "active", "paused", "orphaned", "error" ] } }, { "name": "pair_id", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor from the previous page." } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/links/{id}": { "get": { "tags": [ "Connectors" ], "summary": "Get link", "description": "Retrieve one link: state, counts, and embedded active_run/last_run. Poll this after POST /transfer.", "operationId": "getConnectorLink", "responses": { "200": { "description": "Link detail" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Link not found" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] }, "patch": { "tags": [ "Connectors" ], "summary": "Update link", "description": "Pause/resume a link (state \"paused\" | \"ready\"), change its mode (synced -> once is the sync downgrade), or edit its policy in place.", "operationId": "updateConnectorLink", "responses": { "200": { "description": "Updated link" }, "400": { "description": "Invalid state change" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Link not found" }, "409": { "description": "Clio selection changed or its sync is still running" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "paused", "ready" ] }, "mode": { "type": "string", "enum": [ "once", "synced" ] }, "remote": { "type": "object", "description": "For unpaired Clio document imports only: expand folder_id to its verified Clio matter root. Connection, matter, vault and ledger remain unchanged." }, "expected_remote": { "type": "object", "description": "Required saved remote when expanding a Clio import root; detects concurrent source changes." }, "expected_policy": { "type": "object", "description": "Optional saved Clio import policy. Rejects concurrent changes to its folder/file exclusions." }, "policy": { "type": "object", "description": "Replaces the entire stored policy; omitted fields return to defaults. Repeat deletes, collisions and filters that should be retained. Folder/file exclusions require deletes: preserve (the default)." } } } } } }, "x-permissions": [ "connectors" ] }, "delete": { "tags": [ "Connectors" ], "summary": "Delete link", "description": "Delete a link and its ledger. vault_docs=delete additionally removes the vault documents an import link brought in (default: keep).", "operationId": "deleteConnectorLink", "responses": { "202": { "description": "Link deleted; vault document cleanup scheduled" }, "204": { "description": "Link deleted" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Link not found" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "vault_docs", "in": "query", "schema": { "type": "string", "enum": [ "keep", "delete" ], "default": "keep" } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/links/{id}/objects": { "get": { "tags": [ "Connectors" ], "summary": "List link objects (ledger)", "description": "Per-file transfer ledger for a link: provider item, vault object, path, content version, state, and error.", "operationId": "listConnectorLinkObjects", "responses": { "200": { "description": "Ledger rows" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Link not found" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "schema": { "type": "string", "enum": [ "pending", "transferring", "ingesting", "synced", "skipped", "failed", "tombstoned" ] } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/links/{id}/selection": { "get": { "tags": [ "Connectors" ], "summary": "Get Clio selection root", "description": "Resolve the linked Clio matter root and existing folder ancestry for managing synced folders. Applies the provider account ACLs.", "operationId": "getClioSelectionRoot", "responses": { "200": { "description": "Link detail" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Link not found" } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "connectors" ] } }, "/connectors/v1/sync-link": { "post": { "tags": [ "Connectors" ], "summary": "Create or upgrade a synced link", "description": "Standing promise: backfill now, then stay current (the sync sweeper re-runs synced links on a schedule). Direction both creates paired import/export links and defaults export to a CaseMark Output subfolder. Same body as /transfer minus run_mode. Upserts links by (connection_id, direction, remote, vault_id); existing once-links are upgraded in place with their ledger and cursor preserved. Downgrade or pause via PATCH /links/{id}.", "operationId": "createConnectorSyncLink", "responses": { "201": { "description": "Synced link created/upgraded; backfill or incremental run in progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object" } }, "runs": { "type": "array", "description": "Start result for each link when direction is both.", "items": { "type": "object", "required": [ "link_id", "started" ], "properties": { "link_id": { "type": "string" }, "started": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "stale_run_recovery", "already_running", "ingestion_backlog" ] }, "backlog": { "type": "integer", "minimum": 0 } } } }, "run": { "type": "object", "description": "Whether a provider scan started or was deferred.", "required": [ "started" ], "properties": { "started": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "stale_run_recovery", "already_running", "ingestion_backlog" ] }, "backlog": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions or provider does not support export" }, "404": { "description": "Connection or vault not found" }, "409": { "description": "Connection is not ready, import selection conflicts, or Smokeball is at capacity. data.error.code=connection_capacity means retry after an active import finishes; connection_not_ready means reconnect.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "enum": [ 409 ] }, "statusMessage": { "type": "string" }, "data": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "connection_not_ready", "connection_capacity", "import_selection_conflict" ] }, "status": { "type": "string" } }, "required": [ "code" ] } } } } } } } } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "direction", "connection_id", "remote", "vault_id" ], "properties": { "direction": { "type": "string", "enum": [ "import", "export", "both" ] }, "connection_id": { "type": "string" }, "remote": { "type": "object", "required": [ "folder_id" ], "properties": { "site_id": { "type": "string" }, "container_id": { "type": "string" }, "folder_id": { "type": "string" }, "path": { "type": "string" }, "resource_type": { "type": "string" } } }, "export_destination": { "type": "object", "description": "Optional destination for direction both. Defaults to CaseMark Output under remote.", "required": [ "folder_id" ], "properties": { "site_id": { "type": "string" }, "container_id": { "type": "string" }, "folder_id": { "type": "string" }, "path": { "type": "string" } } }, "vault_id": { "type": "string" }, "matter_id": { "type": "string", "nullable": true }, "policy": { "type": "object", "properties": { "deletes": { "type": "string", "enum": [ "mirror", "preserve" ] }, "collisions": { "type": "string", "enum": [ "version", "overwrite", "skip" ] }, "filters": { "type": "object", "properties": { "max_size_bytes": { "type": "integer" }, "exclude_mime": { "type": "array", "items": { "type": "string" } }, "exclude_folder_ids": { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 256 }, "description": "Skip these folders and all descendants during document imports." }, "exclude_file_ids": { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 256 }, "description": "Skip these stable document ids before download, including future versions." } } } } } } } } } }, "x-permissions": [ "connectors" ] } }, "/connectors/v1/transfer": { "post": { "tags": [ "Connectors" ], "summary": "Transfer between provider folder and vault", "description": "One-shot import (provider folder → vault), export (vault → provider folder), or both. Direction both creates paired import/export links and defaults export to a CaseMark Output subfolder. Upserts links by (connection_id, direction, remote, vault_id): first call backfills, later calls move only new/changed files via the ledger. Poll GET /links/{id} → active_run for progress.", "operationId": "createConnectorTransfer", "responses": { "202": { "description": "Link created/re-triggered; run in progress", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "array", "items": { "type": "object" } }, "runs": { "type": "array", "description": "Start result for each link when direction is both.", "items": { "type": "object", "required": [ "link_id", "started" ], "properties": { "link_id": { "type": "string" }, "started": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "stale_run_recovery", "already_running", "ingestion_backlog" ] }, "backlog": { "type": "integer", "minimum": 0 } } } }, "run": { "type": "object", "description": "Whether a provider scan started or was deferred.", "required": [ "started" ], "properties": { "started": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "stale_run_recovery", "already_running", "ingestion_backlog" ] }, "backlog": { "type": "integer", "minimum": 0 } } } } } } } }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions or provider does not support export" }, "404": { "description": "Connection or vault not found" }, "409": { "description": "Connection is not ready, import selection conflicts, or Smokeball is at capacity. data.error.code=connection_capacity means retry after an active import finishes; connection_not_ready means reconnect.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "enum": [ 409 ] }, "statusMessage": { "type": "string" }, "data": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "connection_not_ready", "connection_capacity", "import_selection_conflict" ] }, "status": { "type": "string" } }, "required": [ "code" ] } } } } } } } } }, "parameters": [ { "name": "x-case-connector-subject", "in": "header", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,255}$" }, "description": "Trusted server-to-server application-user assertion. Derive it from the authenticated application session, never browser input. Omit only for the legacy organization-scoped namespace." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "direction", "connection_id", "remote", "vault_id" ], "properties": { "direction": { "type": "string", "enum": [ "import", "export", "both" ] }, "connection_id": { "type": "string" }, "remote": { "type": "object", "required": [ "folder_id" ], "properties": { "site_id": { "type": "string" }, "container_id": { "type": "string" }, "folder_id": { "type": "string" }, "path": { "type": "string" }, "resource_type": { "type": "string" } } }, "export_destination": { "type": "object", "description": "Optional destination for direction both. Defaults to CaseMark Output under remote.", "required": [ "folder_id" ], "properties": { "site_id": { "type": "string" }, "container_id": { "type": "string" }, "folder_id": { "type": "string" }, "path": { "type": "string" } } }, "vault_id": { "type": "string" }, "matter_id": { "type": "string", "nullable": true }, "run_mode": { "type": "string", "enum": [ "auto", "full_reconcile" ], "default": "auto" }, "policy": { "type": "object", "properties": { "deletes": { "type": "string", "enum": [ "mirror", "preserve" ] }, "collisions": { "type": "string", "enum": [ "version", "overwrite", "skip" ] }, "filters": { "type": "object", "properties": { "max_size_bytes": { "type": "integer" }, "exclude_mime": { "type": "array", "items": { "type": "string" } }, "exclude_folder_ids": { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 256 }, "description": "Skip these folders and all descendants during document imports." }, "exclude_file_ids": { "type": "array", "maxItems": 1000, "items": { "type": "string", "maxLength": 256 }, "description": "Skip these stable document ids before download, including future versions." } } } } } } } } } }, "x-permissions": [ "connectors" ] } }, "/index": { "get": { "tags": [ "System" ], "summary": "Get API Status", "description": "Returns basic information about the Case.dev API including name, version, and health status. This endpoint can be used for health checks and API discovery.", "operationId": "getApiStatus", "responses": { "200": { "description": "API information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the API" }, "version": { "type": "string", "description": "The current API version" }, "status": { "type": "string", "description": "The health status of the API" } }, "required": [ "name", "version", "status" ] }, "example": { "name": "case.dev API", "version": "1.0.0", "status": "healthy" } } } } } } }, "/legal/v1/citations": { "post": { "tags": [ "Legal" ], "summary": "Parse citations from text", "description": "Parses legal citations from text and returns structured Bluebook components (case name, reporter, volume, page, year, court). Accepts either a single citation or a full text block.", "operationId": "legalCitations", "responses": { "200": { "description": "Citations extracted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "citations": { "type": "array", "items": { "type": "object", "properties": { "original": { "type": "string", "description": "Original citation as found in text" }, "span": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "components": { "type": "object", "nullable": true, "description": "Structured Bluebook components. Null if citation format is not recognized.", "properties": { "caseName": { "type": "string", "description": "Case name, e.g., \"Bush v. Gore\"" }, "volume": { "type": "integer", "description": "Volume number" }, "reporter": { "type": "string", "description": "Reporter abbreviation, e.g., \"U.S.\"" }, "page": { "type": "integer", "description": "Starting page number" }, "year": { "type": "integer", "description": "Decision year" }, "court": { "type": "string", "description": "Court identifier" }, "pinCite": { "type": "integer", "description": "Pin cite (specific page)" } } }, "normalized": { "type": "string", "description": "Normalized citation string" }, "found": { "type": "boolean", "description": "Whether citation was found in CourtListener database" } } } } } } } } }, "400": { "description": "Bad request - invalid or missing text parameter" }, "401": { "description": "Unauthorized - invalid API key" }, "503": { "description": "Service unavailable - CourtListener API unreachable" } }, "requestBody": { "description": "Text containing legal citations to extract", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Text containing citations to extract. Can be a single citation (e.g., \"531 U.S. 98\") or a full document with multiple citations.", "maxLength": 64000 } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/citations-from-url": { "post": { "tags": [ "Legal" ], "summary": "Extract citations from URL", "description": "Extract all legal citations and references from a document URL. Returns structured citation data including case citations, statute references, and regulatory citations.", "operationId": "legalCitationsFromUrl", "responses": { "200": { "description": "Citations extracted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Source document URL" }, "title": { "type": "string", "description": "Document title" }, "totalCitations": { "type": "integer", "description": "Total citations found" }, "citations": { "type": "object", "properties": { "cases": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Citation type (usReporter, federalReporter, etc.)" }, "citation": { "type": "string", "description": "The citation string" }, "count": { "type": "integer", "description": "Number of occurrences" } } } }, "statutes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Citation type (usc)" }, "citation": { "type": "string", "description": "The citation string" }, "count": { "type": "integer", "description": "Number of occurrences" } } } }, "regulations": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Citation type (cfr)" }, "citation": { "type": "string", "description": "The citation string" }, "count": { "type": "integer", "description": "Number of occurrences" } } } } } }, "externalLinks": { "type": "array", "items": { "type": "string" }, "description": "External links found in the document" }, "hint": { "type": "string", "description": "Usage guidance" } } } } } }, "400": { "description": "Bad request - invalid URL" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "503": { "description": "Service unavailable - content service unreachable" } }, "requestBody": { "description": "Document URL to extract citations from", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the legal document to extract citations from" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/courts": { "post": { "tags": [ "Legal" ], "summary": "List federal and state courts", "description": "Returns court IDs (slugs) and names for use with the docket search endpoint. Use the returned court ID as the `court` parameter in legal.docket().", "operationId": "legalListCourts", "responses": { "200": { "description": "Court list retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "nullable": true }, "jurisdiction": { "type": "string", "nullable": true }, "inUseOnly": { "type": "boolean", "description": "Whether results are filtered to in-use courts only" }, "found": { "type": "integer" }, "courts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Court slug (use as the court parameter in legal.docket())" }, "shortName": { "type": "string", "nullable": true }, "fullName": { "type": "string", "nullable": true }, "jurisdiction": { "type": "string", "nullable": true }, "pacerCourtId": { "type": "integer", "nullable": true } } } } } } } } }, "400": { "description": "Bad request - invalid parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" } }, "requestBody": { "description": "Court lookup options", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Search by court name or slug (e.g. \"Northern District\", \"nysd\", \"ca9\")", "minLength": 2, "maxLength": 100 }, "jurisdiction": { "type": "string", "description": "Optional jurisdiction code filter (e.g. FD for Federal District, F for all Federal, S for State)" }, "inUseOnly": { "type": "boolean", "default": true, "description": "Only return courts with available docket data" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of courts to return" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Number of courts to skip before returning results" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/docket": { "post": { "tags": [ "Legal" ], "summary": "Search federal dockets and filings", "description": "Search federal court dockets or retrieve a specific docket with optional filing entries. Use legal.listCourts() to resolve court slugs for filtering.", "operationId": "legalDocket", "responses": { "200": { "description": "Docket query completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search", "lookup" ] }, "query": { "type": "string", "nullable": true, "description": "Echo of search query (search mode only)" }, "court": { "type": "string", "nullable": true, "description": "Echo of court filter (search mode only)" }, "dateFiledAfter": { "type": "string", "format": "date", "nullable": true, "description": "Echo of date filter" }, "dateFiledBefore": { "type": "string", "format": "date", "nullable": true, "description": "Echo of date filter" }, "found": { "type": "integer" }, "dockets": { "title": "DocketSearchResults", "type": "array", "description": "Search results (search mode)", "items": { "title": "DocketSearchResult", "type": "object", "properties": { "id": { "type": "string" }, "caseName": { "type": "string", "nullable": true }, "docketNumber": { "type": "string", "nullable": true }, "court": { "type": "string", "nullable": true }, "courtId": { "type": "string", "nullable": true }, "dateFiled": { "type": "string", "format": "date", "nullable": true }, "dateTerminated": { "type": "string", "format": "date", "nullable": true }, "cause": { "type": "string", "nullable": true }, "natureOfSuit": { "type": "string", "nullable": true }, "parties": { "type": "array", "items": { "type": "string" } }, "assignedTo": { "type": "string", "nullable": true }, "url": { "type": "string" }, "pacerCaseId": { "type": "string", "nullable": true } } } }, "includeEntries": { "type": "boolean", "description": "Whether entries were requested (lookup mode only)" }, "docket": { "title": "DocketDetail", "type": "object", "nullable": true, "description": "Full docket record (lookup mode)", "properties": { "id": { "type": "string" }, "caseName": { "type": "string", "nullable": true }, "docketNumber": { "type": "string", "nullable": true }, "court": { "type": "string", "nullable": true }, "courtId": { "type": "string", "nullable": true }, "dateFiled": { "type": "string", "format": "date", "nullable": true }, "dateTerminated": { "type": "string", "format": "date", "nullable": true }, "cause": { "type": "string", "nullable": true }, "natureOfSuit": { "type": "string", "nullable": true }, "parties": { "type": "array", "items": { "type": "string" } }, "assignedTo": { "type": "string", "nullable": true }, "url": { "type": "string" }, "pacerCaseId": { "type": "string", "nullable": true } } }, "entries": { "type": "array", "nullable": true, "description": "Docket entries/filings (lookup mode with includeEntries)", "items": { "type": "object", "properties": { "entryNumber": { "type": "integer", "nullable": true }, "date": { "type": "string", "format": "date", "nullable": true }, "description": { "type": "string", "nullable": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "documentNumber": { "type": "string", "nullable": true }, "attachmentNumber": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true }, "pdfUrl": { "type": "string", "nullable": true }, "pageCount": { "type": "integer", "nullable": true }, "isAvailable": { "type": "boolean" } } } } } } }, "pagination": { "type": "object", "nullable": true, "description": "Pagination info for entry list (lookup mode with includeEntries)", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "returned": { "type": "integer" } } }, "live": { "type": "boolean", "description": "Whether this was a live PACER fetch (lookup mode only)" }, "pacerFees": { "type": "object", "nullable": true, "description": "PACER fee information (present when live: true)", "properties": { "serviceFee": { "type": "number", "description": "CaseMark service fee in USD" }, "maxPacerCost": { "type": "number", "description": "Maximum PACER charge per docket in USD" }, "currency": { "type": "string", "enum": [ "USD" ] }, "fetchDurationMs": { "type": "integer", "description": "Time taken for PACER fetch in milliseconds" } } } } } } } }, "400": { "description": "Bad request - invalid parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "404": { "description": "Docket not found" }, "429": { "description": "Too many requests - daily PACER spend cap exceeded" }, "502": { "description": "Bad gateway - upstream provider error" }, "503": { "description": "Service unavailable - docket data source not configured" } }, "requestBody": { "description": "Docket query parameters", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "search", "lookup" ], "description": "Search dockets or look up a docket by ID" }, "query": { "type": "string", "description": "Case name or party name search query (required for search)", "minLength": 2, "maxLength": 500 }, "court": { "type": "string", "description": "Optional court slug for filtering (e.g. \"nysd\", \"ca9\", \"cafc\"). Use legal.listCourts() to find slugs." }, "dateFiledAfter": { "type": "string", "format": "date", "description": "Optional lower bound for filing date (YYYY-MM-DD)" }, "dateFiledBefore": { "type": "string", "format": "date", "description": "Optional upper bound for filing date (YYYY-MM-DD)" }, "docketId": { "type": "string", "description": "Docket ID (required for lookup)" }, "includeEntries": { "type": "boolean", "default": false, "description": "Include docket entries/filings in lookup responses." }, "live": { "type": "boolean", "default": false, "description": "Trigger a live PACER fetch for dockets not yet in the RECAP archive. Requires acknowledgePacerFees: true. PACER charges up to $3.00 per docket sheet plus a $0.05 service fee. Only valid with type: \"lookup\"." }, "acknowledgePacerFees": { "type": "boolean", "default": false, "description": "Required when live: true. Acknowledges that PACER fees (up to $3.00 per docket) plus a $0.05 service fee will be charged to your account." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Page size for search results or entry list (default 25 for search, 50 for lookup)" }, "offset": { "type": "integer", "minimum": 0, "maximum": 200, "default": 0, "description": "Offset for search results or entry list (maximum 200 when including lookup entries)" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/find": { "post": { "tags": [ "Legal" ], "summary": "Find legal sources", "description": "Search for legal sources including cases, statutes, and regulations from authoritative legal databases. Returns ranked candidates. Always verify with legal.verify() before citing.", "operationId": "legalFind", "responses": { "200": { "description": "Search completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Original search query" }, "jurisdiction": { "type": "string", "description": "Jurisdiction filter applied" }, "found": { "type": "integer", "description": "Number of candidates found" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the legal source" }, "title": { "type": "string", "description": "Title of the document" }, "snippet": { "type": "string", "description": "Text excerpt from the document" }, "source": { "type": "string", "description": "Domain of the source" } } } }, "hint": { "type": "string", "description": "Usage guidance" } } } } } }, "400": { "description": "Bad request - invalid query parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "503": { "description": "Service unavailable - search service unreachable" } }, "requestBody": { "description": "Search query and filtering options", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Search query (e.g., \"fair use copyright\", \"Miranda rights\")", "minLength": 3, "maxLength": 1000 }, "jurisdiction": { "type": "string", "description": "Optional jurisdiction ID from resolveJurisdiction (e.g., \"california\", \"us-federal\")" }, "numResults": { "type": "integer", "description": "Number of results 1-25 (default: 10)", "minimum": 1, "maximum": 25, "default": 10 } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/full-text": { "post": { "tags": [ "Legal" ], "summary": "Get full text of legal document", "description": "Retrieve the full text content of a legal document. Use after verifying the source with legal.verify(). Returns complete text with optional highlights and AI summary.", "operationId": "legalGetFullText", "responses": { "200": { "description": "Document content retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Document URL" }, "title": { "type": "string", "description": "Document title" }, "publishedDate": { "type": "string", "description": "Publication date", "nullable": true }, "author": { "type": "string", "description": "Author or court", "nullable": true }, "text": { "type": "string", "description": "Full document text" }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Highlighted relevant passages" }, "summary": { "type": "string", "description": "AI-generated summary", "nullable": true }, "characterCount": { "type": "integer", "description": "Total characters in text" } } } } } }, "400": { "description": "Bad request - invalid URL or parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "503": { "description": "Service unavailable - content service unreachable" } }, "requestBody": { "description": "URL and retrieval options", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the verified legal document" }, "maxCharacters": { "type": "integer", "description": "Maximum characters to return (default: 10000, max: 50000)", "minimum": 1000, "maximum": 50000, "default": 10000 }, "highlightQuery": { "type": "string", "description": "Optional query to extract relevant highlights (e.g., \"What is the holding?\")" }, "summaryQuery": { "type": "string", "description": "Optional query for generating a summary (e.g., \"Summarize the key ruling\")" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/health": { "get": { "tags": [ "Legal" ], "summary": "Health check", "description": "Unauthenticated health check for the Citations service. Verifies connectivity to the CourtListener API.", "operationId": "getCitationsHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "upstream": { "type": "object", "properties": { "courtlistener": { "type": "string", "enum": [ "ok", "unavailable" ] } } } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "citations", "upstream": { "courtlistener": "ok" } } } } } } } }, "/legal/v1/jurisdictions": { "post": { "tags": [ "Legal" ], "summary": "Resolve jurisdiction", "description": "Search for a jurisdiction by name. Returns matching jurisdictions with their IDs for use in legal.find() and other legal research endpoints.", "operationId": "legalResolveJurisdiction", "responses": { "200": { "description": "Jurisdictions found successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Original search query" }, "found": { "type": "integer", "description": "Number of matching jurisdictions" }, "jurisdictions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Jurisdiction ID to use in other endpoints" }, "name": { "type": "string", "description": "Full jurisdiction name" }, "level": { "type": "string", "enum": [ "federal", "state", "county", "municipal" ], "description": "Jurisdiction level" }, "state": { "type": "string", "description": "State abbreviation (if applicable)", "nullable": true } } } }, "hint": { "type": "string", "description": "Usage guidance" } } } } } }, "400": { "description": "Bad request - invalid search term" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" } }, "requestBody": { "description": "Jurisdiction search query", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Jurisdiction name (e.g., \"California\", \"US Federal\", \"NY\")", "minLength": 2, "maxLength": 100 } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/patent-search": { "post": { "tags": [ "Legal" ], "summary": "Search USPTO patent applications", "description": "Search the USPTO Open Data Portal for US patent applications and granted patents. Supports free-text queries, field-specific search, filters by assignee/inventor/status/type, date ranges, and pagination. Covers applications filed on or after January 1, 2001. Data is refreshed daily.", "operationId": "patentSearch", "responses": { "200": { "description": "Patent search completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Original search query" }, "totalResults": { "type": "integer", "description": "Total number of matching patent applications" }, "offset": { "type": "integer", "description": "Current pagination offset" }, "limit": { "type": "integer", "description": "Number of results returned" }, "results": { "type": "array", "description": "Array of matching patent applications", "items": { "type": "object", "properties": { "applicationNumber": { "type": "string", "description": "Patent application serial number" }, "patentNumber": { "type": "string", "description": "Granted patent number (if granted)", "nullable": true }, "title": { "type": "string", "description": "Invention title" }, "applicationType": { "type": "string", "description": "Application type (Utility, Design, Plant, etc.)" }, "status": { "type": "string", "description": "Current application status (e.g. \"Patented Case\", \"Pending\")" }, "filingDate": { "type": "string", "format": "date", "description": "Date the application was filed", "nullable": true }, "grantDate": { "type": "string", "format": "date", "description": "Date the patent was granted", "nullable": true }, "inventors": { "type": "array", "items": { "type": "string" }, "description": "List of inventor names" }, "assignees": { "type": "array", "items": { "type": "string" }, "description": "List of assignee/owner names" }, "entityStatus": { "type": "string", "description": "Entity status (e.g. \"Small Entity\", \"Micro Entity\")", "nullable": true } } } } } } } } }, "400": { "description": "Bad request - invalid query or parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions for Legal service" }, "502": { "description": "Bad gateway - USPTO API returned an error" } }, "requestBody": { "description": "Patent search query and filters", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Free-text search across all patent fields, or field-specific query (e.g. \"applicationMetaData.patentNumber:11234567\"). Supports AND, OR, NOT operators.", "minLength": 1 }, "applicationStatus": { "type": "string", "description": "Filter by application status (e.g. \"Patented Case\", \"Abandoned\", \"Pending\")" }, "applicationType": { "type": "string", "enum": [ "Utility", "Design", "Plant", "Provisional", "Reissue" ], "description": "Filter by application type" }, "assignee": { "type": "string", "description": "Filter by assignee/owner name (e.g. \"Google LLC\")" }, "inventor": { "type": "string", "description": "Filter by inventor name" }, "filingDateFrom": { "type": "string", "format": "date", "description": "Start of filing date range (YYYY-MM-DD)" }, "filingDateTo": { "type": "string", "format": "date", "description": "End of filing date range (YYYY-MM-DD)" }, "grantDateFrom": { "type": "string", "format": "date", "description": "Start of grant date range (YYYY-MM-DD)" }, "grantDateTo": { "type": "string", "format": "date", "description": "End of grant date range (YYYY-MM-DD)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Number of results to return (default 25, max 100)" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Starting position for pagination" }, "sortBy": { "type": "string", "enum": [ "filingDate", "grantDate" ], "default": "filingDate", "description": "Field to sort results by" }, "sortOrder": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort order (default desc, newest first)" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/research": { "post": { "tags": [ "Legal" ], "summary": "Deep legal research", "description": "Perform comprehensive legal research with multiple query variations. Uses advanced deep search to find relevant sources across different phrasings of the legal issue.", "operationId": "legalDeepResearch", "responses": { "200": { "description": "Research completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Primary search query" }, "additionalQueries": { "type": "array", "items": { "type": "string" }, "description": "Additional queries used", "nullable": true }, "jurisdiction": { "type": "string", "description": "Jurisdiction filter applied" }, "searchType": { "type": "string", "description": "Search type used (deep)" }, "found": { "type": "integer", "description": "Number of candidates found" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the legal source" }, "title": { "type": "string", "description": "Title of the document" }, "snippet": { "type": "string", "description": "Text excerpt from the document" }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Highlighted relevant passages" }, "publishedDate": { "type": "string", "description": "Publication date", "nullable": true }, "source": { "type": "string", "description": "Domain of the source" } } } }, "hint": { "type": "string", "description": "Usage guidance" } } } } } }, "400": { "description": "Bad request - invalid query parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "503": { "description": "Service unavailable - search service unreachable" } }, "requestBody": { "description": "Research query and options", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Primary search query", "minLength": 3, "maxLength": 1000 }, "additionalQueries": { "type": "array", "items": { "type": "string" }, "description": "Additional query variations to search (e.g., different phrasings of the legal issue)", "maxItems": 5 }, "jurisdiction": { "type": "string", "description": "Optional jurisdiction ID from resolveJurisdiction" }, "numResults": { "type": "integer", "description": "Number of results 1-25 (default: 10)", "minimum": 1, "maximum": 25, "default": 10 } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/sec-filing": { "post": { "tags": [ "Legal" ], "summary": "Search EDGAR filings and entity history", "description": "Search SEC EDGAR full-text filings via efts.sec.gov or fetch a filer's structured filing history via data.sec.gov. Returns direct SEC archive URLs with filing metadata and match snippets when available.", "operationId": "legalSecFiling", "responses": { "200": { "description": "SEC filings retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search", "entity" ] }, "query": { "type": "string", "nullable": true }, "entity": { "type": "string", "nullable": true }, "ticker": { "type": "string", "nullable": true }, "cik": { "type": "string", "nullable": true }, "formTypes": { "type": "array", "items": { "type": "string" } }, "dateAfter": { "type": "string", "format": "date", "nullable": true }, "dateBefore": { "type": "string", "format": "date", "nullable": true }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer" }, "filings": { "type": "array", "items": { "type": "object", "properties": { "accessionNumber": { "type": "string" }, "formType": { "type": "string" }, "filedAt": { "type": "string", "format": "date" }, "periodOfReport": { "type": "string", "format": "date", "nullable": true }, "entity": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "cik": { "type": "string" }, "ticker": { "type": "string", "nullable": true }, "sic": { "type": "string", "nullable": true }, "sicDescription": { "type": "string", "nullable": true }, "stateOfIncorporation": { "type": "string", "nullable": true }, "entityType": { "type": "string", "nullable": true } } }, "description": { "type": "string", "nullable": true }, "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string" } } } }, "snippet": { "type": "string", "nullable": true }, "secUrl": { "type": "string" } } } } } } } } }, "400": { "description": "Bad request - invalid SEC filing parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "404": { "description": "Ticker or SEC entity not found" }, "503": { "description": "Service unavailable - SEC upstream unavailable or throttled" } }, "requestBody": { "description": "SEC filing search or entity lookup parameters", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "search", "entity" ], "description": "Run a full-text search or fetch a single entity filing history" }, "query": { "type": "string", "minLength": 2, "maxLength": 1000, "description": "Full-text SEC search query (required for type: search)" }, "formTypes": { "type": "array", "description": "Optional SEC form type filter such as 10-K, 10-Q, 8-K, or 4", "items": { "type": "string" } }, "ticker": { "type": "string", "description": "Optional company ticker. Valid for both search and entity lookups." }, "entity": { "type": "string", "description": "Optional entity filter passed through to EDGAR full-text search" }, "cik": { "type": "string", "description": "CIK for entity lookups. Accepts padded or unpadded digits." }, "dateAfter": { "type": "string", "format": "date", "description": "Optional lower filing date bound (YYYY-MM-DD)" }, "dateBefore": { "type": "string", "format": "date", "description": "Optional upper filing date bound (YYYY-MM-DD)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum filings to return" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Result offset for pagination" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/sec-xbrl": { "post": { "tags": [ "Legal" ], "summary": "Structured XBRL financial data from SEC filings", "description": "Retrieve structured financial values reported to the SEC in XBRL, via data.sec.gov. Use this endpoint when you need numbers (net income, assets, shares outstanding, and so on); use sec-filing to find filing documents. Three types: \"concept\" returns one line item for one company over time; \"facts\" returns a catalog of every concept a company reports (or normalized facts for the concepts you name); \"frames\" returns one concept across all reporting companies for one calendar period. Each fact links back to its EDGAR filing index via secUrl. The same value is re-reported in later filings as a prior-period comparative, so by default (dedupe: true) only facts the SEC assigned a calendar frame are returned; set dedupe to false for every reported fact. Free.", "operationId": "legalSecXbrl", "responses": { "200": { "description": "XBRL data retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "concept", "facts", "frames" ] }, "cik": { "type": "string", "description": "Padded CIK (concept and facts)" }, "ticker": { "type": "string", "nullable": true }, "entityName": { "type": "string", "nullable": true }, "taxonomy": { "type": "string", "nullable": true }, "tag": { "type": "string", "description": "concept and frames" }, "unit": { "type": "string", "nullable": true }, "period": { "type": "string", "description": "frames only" }, "sort": { "type": "string", "description": "frames only" }, "label": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "dedupe": { "type": "boolean", "description": "concept and facts with concepts" }, "formTypes": { "type": "array", "items": { "type": "string" } }, "fiscalPeriods": { "type": "array", "items": { "type": "string" } }, "dateAfter": { "type": "string", "format": "date", "nullable": true }, "dateBefore": { "type": "string", "format": "date", "nullable": true }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "total": { "type": "integer", "description": "Rows matching before pagination" }, "facts": { "type": "array", "description": "concept, and facts when concepts is provided", "items": { "type": "object", "properties": { "taxonomy": { "type": "string" }, "tag": { "type": "string" }, "label": { "type": "string", "nullable": true }, "unit": { "type": "string", "description": "For example USD, shares, or USD/shares" }, "value": { "type": "number" }, "start": { "type": "string", "format": "date", "nullable": true, "description": "Null for instantaneous facts" }, "end": { "type": "string", "format": "date" }, "fiscalYear": { "type": "integer", "nullable": true }, "fiscalPeriod": { "type": "string", "nullable": true }, "form": { "type": "string", "nullable": true }, "filed": { "type": "string", "format": "date", "nullable": true }, "accessionNumber": { "type": "string", "nullable": true }, "frame": { "type": "string", "nullable": true, "description": "SEC calendar frame, null if not assigned" }, "cik": { "type": "string" }, "entityName": { "type": "string", "nullable": true }, "secUrl": { "type": "string", "nullable": true, "description": "EDGAR filing index URL" }, "loc": { "type": "string", "nullable": true, "description": "frames only. Reporting company location code" } } } }, "concepts": { "type": "array", "description": "facts without concepts: the catalog of concepts the company reports", "items": { "type": "object", "properties": { "taxonomy": { "type": "string" }, "tag": { "type": "string" }, "label": { "type": "string", "nullable": true }, "units": { "type": "array", "items": { "type": "string" } }, "factCount": { "type": "integer" }, "latestPeriodEnd": { "type": "string", "format": "date", "nullable": true } } } }, "data": { "type": "array", "description": "frames: one row per reporting company", "items": { "type": "object", "properties": { "taxonomy": { "type": "string" }, "tag": { "type": "string" }, "label": { "type": "string", "nullable": true }, "unit": { "type": "string", "description": "For example USD, shares, or USD/shares" }, "value": { "type": "number" }, "start": { "type": "string", "format": "date", "nullable": true, "description": "Null for instantaneous facts" }, "end": { "type": "string", "format": "date" }, "fiscalYear": { "type": "integer", "nullable": true }, "fiscalPeriod": { "type": "string", "nullable": true }, "form": { "type": "string", "nullable": true }, "filed": { "type": "string", "format": "date", "nullable": true }, "accessionNumber": { "type": "string", "nullable": true }, "frame": { "type": "string", "nullable": true, "description": "SEC calendar frame, null if not assigned" }, "cik": { "type": "string" }, "entityName": { "type": "string", "nullable": true }, "secUrl": { "type": "string", "nullable": true, "description": "EDGAR filing index URL" }, "loc": { "type": "string", "nullable": true, "description": "frames only. Reporting company location code" } } } } } } } } }, "400": { "description": "Bad request - invalid XBRL parameters (for example a malformed frames period)" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "404": { "description": "Ticker or CIK not found, or no XBRL data for the requested company, concept, or frame" }, "503": { "description": "Service unavailable - SEC upstream unavailable or throttled" } }, "requestBody": { "description": "XBRL query parameters. The fields used depend on type.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "concept", "facts", "frames" ], "description": "concept: one line item for one company over time. facts: all concepts for one company (catalog, or values for the concepts you list). frames: one concept across all companies for one period." }, "cik": { "type": "string", "description": "Company CIK, padded or unpadded (concept and facts). Provide exactly one of cik or ticker." }, "ticker": { "type": "string", "description": "Company ticker (concept and facts). Provide exactly one of cik or ticker." }, "taxonomy": { "type": "string", "enum": [ "us-gaap", "ifrs-full", "dei", "srt" ], "default": "us-gaap", "description": "XBRL taxonomy. For facts it only filters the catalog and has no default." }, "tag": { "type": "string", "description": "XBRL element name such as NetIncomeLoss (required for concept and frames)" }, "concepts": { "type": "array", "items": { "type": "string" }, "description": "facts only. \"taxonomy:tag\" strings or bare tags (default us-gaap). Omit to get the concept catalog, which has no values." }, "unit": { "type": "string", "description": "Unit such as USD, shares, or USD/shares. Optional filter for concept; defaults to USD for frames (the SEC URL form USD-per-shares is also accepted)." }, "period": { "type": "string", "pattern": "^CY\\d{4}(Q[1-4]I?)?$", "description": "frames only, required. CY2024 = annual duration, CY2024Q1 = quarterly duration, CY2024Q1I = instantaneous (balance sheet items)." }, "ciks": { "type": "array", "items": { "type": "string" }, "description": "frames only. Restrict results to these CIKs (peer set)." }, "tickers": { "type": "array", "items": { "type": "string" }, "description": "frames only. Restrict results to these tickers (peer set)." }, "sort": { "type": "string", "enum": [ "value_desc", "value_asc" ], "default": "value_desc", "description": "frames only. Sort order by value." }, "formTypes": { "type": "array", "items": { "type": "string" }, "description": "concept and facts. Filter by SEC form type such as 10-K or 10-Q." }, "fiscalPeriods": { "type": "array", "items": { "type": "string", "enum": [ "FY", "Q1", "Q2", "Q3" ] }, "description": "concept and facts. Filter by fiscal period." }, "dateAfter": { "type": "string", "format": "date", "description": "concept and facts. Only facts whose period end date is on or after this date (YYYY-MM-DD)." }, "dateBefore": { "type": "string", "format": "date", "description": "concept and facts. Only facts whose period end date is on or before this date (YYYY-MM-DD)." }, "dedupe": { "type": "boolean", "default": true, "description": "concept and facts. When true, keep only facts the SEC assigned a calendar frame (its canonical fact per period), dropping prior-period comparatives re-reported in later filings. When false, return every reported fact." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum rows to return" }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "Result offset for pagination" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/similar": { "post": { "tags": [ "Legal" ], "summary": "Find similar legal sources", "description": "Find cases and documents similar to a given legal source. Useful for finding citing cases, related precedents, or similar statutes.", "operationId": "legalFindSimilar", "responses": { "200": { "description": "Similar sources found successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceUrl": { "type": "string", "description": "Original source URL" }, "jurisdiction": { "type": "string", "description": "Jurisdiction filter applied" }, "found": { "type": "integer", "description": "Number of similar sources found" }, "similarSources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the similar source" }, "title": { "type": "string", "description": "Title of the document" }, "snippet": { "type": "string", "description": "Text excerpt from the document" }, "publishedDate": { "type": "string", "description": "Publication date", "nullable": true }, "source": { "type": "string", "description": "Domain of the source" } } } }, "hint": { "type": "string", "description": "Usage guidance" } } } } } }, "400": { "description": "Bad request - invalid URL or parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions" }, "503": { "description": "Service unavailable - similarity service unreachable" } }, "requestBody": { "description": "Source URL and filtering options", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL of a legal document to find similar sources for" }, "jurisdiction": { "type": "string", "description": "Optional jurisdiction ID to filter results" }, "numResults": { "type": "integer", "description": "Number of results 1-25 (default: 10)", "minimum": 1, "maximum": 25, "default": 10 }, "startPublishedDate": { "type": "string", "format": "date", "description": "Optional ISO date to find only newer documents (e.g., \"2020-01-01\")" } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/trademark-search": { "post": { "tags": [ "Legal" ], "summary": "Look up USPTO trademark status", "description": "Look up trademark status and details from the USPTO Trademark Status & Document Retrieval (TSDR) system. Supports lookup by serial number or registration number. Returns mark text, status, owner, goods/services, Nice classification, filing/registration dates, and more.", "operationId": "trademarkSearch", "responses": { "200": { "description": "Trademark lookup completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "serialNumber": { "type": "string", "description": "USPTO serial number" }, "registrationNumber": { "type": "string", "description": "USPTO registration number (if registered)", "nullable": true }, "markText": { "type": "string", "description": "The text of the trademark", "nullable": true }, "markType": { "type": "string", "description": "Type of mark (e.g. \"Standard Character Mark\", \"Design Mark\")", "nullable": true }, "status": { "type": "string", "description": "Current status (e.g. \"Registered\", \"Pending\", \"Abandoned\", \"Cancelled\")", "nullable": true }, "statusDate": { "type": "string", "format": "date", "description": "Date of most recent status update", "nullable": true }, "filingDate": { "type": "string", "format": "date", "description": "Date the application was filed", "nullable": true }, "registrationDate": { "type": "string", "format": "date", "description": "Date the mark was registered", "nullable": true }, "owner": { "type": "object", "description": "Current owner/applicant information", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "entityType": { "type": "string", "nullable": true } } }, "attorney": { "type": "string", "description": "Attorney of record", "nullable": true }, "goodsAndServices": { "type": "array", "description": "Goods and services descriptions with class numbers", "items": { "type": "object", "properties": { "classNumber": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } } } }, "niceClasses": { "type": "array", "items": { "type": "integer" }, "description": "Nice classification class numbers" }, "imageUrl": { "type": "string", "description": "URL to the mark image on USPTO CDN", "nullable": true }, "usptoUrl": { "type": "string", "description": "Canonical TSDR link for this mark" } } } } } }, "400": { "description": "Bad request - must provide serialNumber or registrationNumber" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions for Legal service" }, "404": { "description": "Trademark not found for the given number" }, "500": { "description": "Internal server error" }, "502": { "description": "Bad gateway - USPTO TSDR API returned an error" }, "503": { "description": "Service unavailable - trademark search service is not configured" } }, "requestBody": { "description": "Trademark lookup parameters", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serialNumber": { "type": "string", "description": "USPTO serial number (e.g. \"97123456\"). Provide either serialNumber or registrationNumber." }, "registrationNumber": { "type": "string", "description": "USPTO registration number (e.g. \"6123456\"). Provide either serialNumber or registrationNumber." } } } } } }, "x-permissions": [ "legal" ] } }, "/legal/v1/verify": { "post": { "tags": [ "Legal" ], "summary": "Verify legal citations", "description": "Validates legal citations against authoritative case law sources (CourtListener database of ~10M cases). Returns verification status and case metadata for each citation found in the input text. Accepts either a single citation or a full text block containing multiple citations.", "operationId": "verifyCitations", "responses": { "200": { "description": "Citations verified successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total citations found" }, "verified": { "type": "integer", "description": "Citations verified against real cases" }, "notFound": { "type": "integer", "description": "Citations not found in database" }, "multipleMatches": { "type": "integer", "description": "Citations with multiple possible matches" } } }, "citations": { "type": "array", "items": { "type": "object", "properties": { "original": { "type": "string", "description": "Original citation as found in text" }, "span": { "type": "object", "properties": { "start": { "type": "integer" }, "end": { "type": "integer" } } }, "status": { "type": "string", "enum": [ "verified", "not_found", "multiple_matches" ] }, "verificationSource": { "type": "string", "description": "Source of verification result (heuristic for fallback matches).", "enum": [ "courtlistener", "heuristic" ] }, "confidence": { "type": "number", "description": "Confidence score (1.0 for CourtListener, heuristic score for fallback)." }, "normalized": { "type": "string", "description": "Normalized citation string" }, "case": { "type": "object", "description": "Case metadata (when verified)", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "shortName": { "type": "string" }, "court": { "type": "string" }, "dateDecided": { "type": "string" }, "docketNumber": { "type": "string" }, "parallelCitations": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" } } }, "candidates": { "type": "array", "description": "Multiple candidates (when multiple_matches or heuristic verification)", "items": { "type": "object", "properties": { "name": { "type": "string" }, "court": { "type": "string" }, "dateDecided": { "type": "string" }, "url": { "type": "string" } } } } } } } } } } } }, "400": { "description": "Bad request - invalid or missing text parameter" }, "401": { "description": "Unauthorized - invalid API key" }, "503": { "description": "Service unavailable - CourtListener API unreachable" } }, "requestBody": { "description": "Text containing legal citations to verify", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Text containing citations to verify. Can be a single citation (e.g., \"531 U.S. 98\") or a full document with multiple citations.", "maxLength": 64000 } } } } } }, "x-permissions": [ "legal" ] } }, "/linc/v1/images": { "post": { "tags": [ "Agents/Linc" ], "summary": "Upload a runtime image for model input", "description": "Inference transport for Linc. Stores a private image without creating a Vault object and returns a renewable presigned download URL. Requires API-key authentication with inference read access.", "operationId": "uploadLincRuntimeImageV1", "responses": { "200": { "description": "Image stored; signed URL lifetime accounts for credential expiry", "content": { "application/json": { "schema": { "type": "object", "required": [ "sha256", "url", "expiresAt" ], "properties": { "sha256": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid image type, encoding, session ID or checksum" }, "401": { "description": "API key authentication required" }, "403": { "description": "Inference read access required" }, "413": { "description": "Image too large" }, "503": { "description": "Image signing credentials need renewal" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sessionId", "sha256", "mimeType", "data" ], "properties": { "sessionId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$", "description": "Native Linc session ID" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 of the decoded image bytes" }, "mimeType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/gif", "image/webp" ] }, "data": { "type": "string", "format": "byte", "maxLength": 2097152, "description": "Canonical base64 image, at most 1.5 MiB decoded" } } } } } }, "x-permissions": [ "llm:read" ] } }, "/linc/v1/sessions": { "post": { "tags": [ "Agents/Linc" ], "summary": "Create native Linc session", "description": "Creates a native Linc session in a sandboxed runtime with scoped Case.dev credentials. This endpoint starts the sandbox actor only; messages and event replay use separate endpoints.", "operationId": "createLincSessionV1", "responses": { "200": { "description": "Linc session created" }, "202": { "description": "Linc session is provisioning. When skillSlugs were requested, `skills` reports exactly what will be preinstalled into the sandbox (loaded) and which slugs did not resolve in the skills registry (missing).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "modelFallbacks": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 8, "uniqueItems": true, "description": "Echoes the explicit policy accepted for a newly provisioned session. Omitted when no policy was requested. Reusing an existing workspace conversation does not change its policy." }, "skillsDelivery": { "type": "string", "enum": [ "local", "mcp" ] }, "runtimeRetention": { "type": "string", "enum": [ "days", "indefinite" ], "description": "indefinite: the runtime is kept until the session or workspace is deleted. days: see runtimeRetentionDays." }, "runtimeRetentionDays": { "type": "integer", "nullable": true, "description": "Days the runtime is kept after its last activity (see request); null when runtimeRetention is indefinite." }, "skills": { "type": "object", "nullable": true, "description": "Present when skillSlugs were requested: the skill preinstall report.", "properties": { "requested": { "type": "array", "items": { "type": "string" } }, "loaded": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "source": { "type": "string", "enum": [ "custom", "curated" ] }, "fileCount": { "type": "integer" } } } }, "missing": { "type": "array", "items": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Vault not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "422": { "description": "None of the requested skillSlugs resolved in the skills registry (custom or curated)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "ai-reporting-user", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Stable internal user or customer identifier for AI Gateway cost reporting." }, { "name": "ai-reporting-tags", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Comma-separated AI Gateway reporting tags. At most 10 unique tags, each 1–64 characters." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "model": { "type": "string", "nullable": true }, "modelFallbacks": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 8, "uniqueItems": true, "description": "Optional ordered availability fallbacks for this session. Requires an explicit model. An empty array disables fallbacks; omission preserves existing runtime behavior. Linc switches within the same session, preserving context." }, "serviceTier": { "type": "string", "enum": [ "default", "priority" ], "description": "Processing tier for eligible OpenAI GPT models. Priority provides lower latency at premium cost." }, "idleTimeoutMs": { "type": "integer", "nullable": true }, "workspaceKey": { "type": "string", "maxLength": 512, "description": "Opt-in persistent workspace identity. Requires conversationKey. Omit both fields to preserve isolated legacy session behavior." }, "conversationKey": { "type": "string", "maxLength": 512, "description": "Stable conversation identity within workspaceKey. Required in workspace mode and idempotent for repeated creates." }, "runtimeRetentionDays": { "type": "integer", "minimum": 1, "maximum": 30, "default": 1, "description": "Days the runtime and its saved state are kept after the last activity. Defaults to 1 for standalone sessions; workspace-mode conversations (workspaceKey) and the C3 system key default to indefinite (see runtimeRetention). Once they are deleted, commands to the session answer 410 linc_runtime_expired; its events stay readable. A workspace keeps the value it was created with; a larger value on a later conversation raises it. Applies to Vercel Sandbox runtimes; accepted and stored on Daytona, where it has no effect. Mutually exclusive with runtimeRetention." }, "runtimeRetention": { "type": "string", "enum": [ "indefinite" ], "description": "indefinite keeps the runtime and its saved state until the session (or, in workspace mode, its last conversation) is deleted, so a chat can resume after any idle gap. The default in workspace mode; standalone chats opt in with it, one-off runs leave it unset. Raises an existing workspace to indefinite. Mutually exclusive with runtimeRetentionDays." }, "capabilityPolicy": { "type": "string", "enum": [ "read_only" ], "description": "Optional server-enforced capability profile. read_only grants only retrieval/inference service reads; session event ingestion remains bound to the exact managed runtime credential." }, "vaultIds": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Legacy explicit whole-vault scope. Mutually exclusive with vaultScopes." }, "vaultScopes": { "type": "array", "nullable": true, "description": "Exact object allowlist per vault. Empty objectIds denies object access for that vault. Mutually exclusive with vaultIds.", "items": { "type": "object", "required": [ "vaultId", "objectIds" ], "properties": { "vaultId": { "type": "string" }, "objectIds": { "type": "array", "items": { "type": "string" } } } } }, "scopedApiKey": { "type": "string", "nullable": true, "description": "Optional caller-provided scoped Case.dev API key for the runtime." }, "instructions": { "type": "string", "nullable": true, "description": "Privileged C3-only hidden app instructions to append to the sandbox AGENTS.md." }, "skillSlugs": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Skills API slugs to install into the runtime sandbox before the native session starts." }, "skillsDelivery": { "type": "string", "enum": [ "local", "mcp" ], "description": "Defaults to local preinstallation. MCP is an opt-in, org-allowlisted rollout on a separately pinned image; requires a new standalone session and no skillSlugs preinstallation. Execution remains content-approval gated." }, "includeDocumentTemplates": { "type": "boolean", "nullable": true, "description": "When true, inject all active org document templates into the using-document-templates skill." }, "documentTemplateSlugs": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Specific document template slugs to inject into the using-document-templates skill." }, "extensions": { "type": "array", "maxItems": 10, "nullable": true, "description": "Optional caller-supplied executable tool files to install into .linc/extensions/ before the agent starts. Only supported for standalone sessions without capabilityPolicy: read_only. Rejected with a 400 on persistent (workspaceKey/conversationKey) or read_only sessions. At most 10 files, 64KB each, 256KB total. Extension destinations and content hashes are recorded in the session-created audit event; raw code is not logged.", "items": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "maxLength": 128, "description": "Bare .ts/.js filename or one-level subdir (e.g. create-automations.ts or automations/index.ts). Each directory must include exactly one index.ts or index.js entrypoint; helper files may accompany it. Platform names (casedev/subagent), root index.ts/index.js, node_modules, hidden top-level names, absolute paths, \"..\", and other extensions or nesting are rejected." }, "content": { "type": "string", "maxLength": 65536, "description": "UTF-8 tool file content, at most 64KB." } } } } } } } } }, "x-permissions": [ "agent:write" ] } }, "/linc/v1/sessions/{id}": { "delete": { "tags": [ "Agents/Linc" ], "summary": "End native Linc session", "operationId": "deleteLincSessionV1", "responses": { "200": { "description": "Linc session ended" }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Linc session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Linc session ID" }, { "name": "reason", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user_deleted", "replaced_scope_changed", "replaced_missing_session", "replaced_runtime_unavailable" ], "default": "user_deleted" }, "description": "Why the session is being ended; recorded in the linc.session.ended event payload. Unknown values fall back to user_deleted. The replaced_* values distinguish automatic session replacement (e.g. by C3) from a user-initiated deletion." } ], "x-permissions": [ "agent:write" ] } }, "/linc/v1/sessions/{id}/cancel": { "post": { "tags": [ "Agents/Linc" ], "summary": "Cancel native Linc session turn", "description": "Sends an abort RPC to the session runtime, ending the current turn while keeping the session alive. Body handling is intentionally lenient — cancel is a stop control, so unknown fields are ignored and an invalid or missing body is treated as empty rather than rejected.", "operationId": "cancelLincSessionTurnV1", "responses": { "200": { "description": "Cancel accepted. Includes the native Pi RPC abort response as `response` (with `response.data.clearedQueue` when clearQueue was requested and the runtime supports it)." }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Linc session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "clearQueue": { "type": "boolean", "description": "Also clear queued steering/follow-up messages so the abort leaves the agent fully idle. Cleared texts are returned in the `response.data.clearedQueue` field of the response body. Without it, messages still queued when the abort settles are auto-continued as a new run. Runtimes older than the Linc release that supports this flag ignore it: the abort still happens but the queue is left untouched." } } } } } }, "x-permissions": [ "agent:write" ] } }, "/linc/v1/sessions/{id}/events": { "get": { "tags": [ "Agents/Linc" ], "summary": "Replay native Linc events", "description": "Returns persisted native Pi/Linc event envelopes after the requested cursor. Live delivery is handled by the Linc stream service.", "operationId": "getLincSessionEventsV1", "responses": { "200": { "description": "Native Linc events" }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or local Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Linc session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Linc session ID" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Replay events with a sequence number greater than this cursor." }, { "name": "afterSeq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Alias for cursor. Ignored when cursor is also provided." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000 }, "description": "Maximum number of events to return." }, { "name": "excludeEventTypes", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "description": "Comma-separated Linc event types to omit from replay." } ], "x-permissions": [ "agent:read" ] } }, "/linc/v1/sessions/{id}/events/ingest": { "post": { "tags": [ "Agents/Linc" ], "summary": "Ingest native Linc session events", "description": "Runtime ingest endpoint for sandbox runtimes. Frames are persisted for replay; terminal frames emit the durable Linc session ended webhook.", "operationId": "ingestLincSessionEventsV1", "responses": { "202": { "description": "Linc events accepted" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent read access", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Linc session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Linc session ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "frames" ], "properties": { "frames": { "type": "array", "description": "Native Linc event frames to persist for replay.", "items": { "type": "object", "required": [ "seq", "type", "event" ], "properties": { "seq": { "type": "integer", "minimum": 1, "description": "Monotonic native event sequence number." }, "type": { "type": "string", "description": "Native Linc event type." }, "event": { "type": "object", "additionalProperties": true, "description": "Native Linc event payload." } } } } } } } } }, "x-permissions": [ "agent:read" ] } }, "/linc/v1/sessions/{id}/messages": { "get": { "tags": [ "Agents/Linc" ], "summary": "Replay completed native Linc messages", "description": "Returns completed Pi/Linc message entries derived from durable native Linc events. This is the stable session-message read model for callers that need to persist or recover chat history without depending on a live SSE stream.", "operationId": "getLincSessionMessagesV1", "responses": { "200": { "description": "Completed native Linc messages" }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or local Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Linc session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Linc session ID" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Replay messages with a source event sequence number greater than this cursor." }, { "name": "afterSeq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Alias for cursor. Ignored when cursor is also provided." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000 }, "description": "Maximum number of source events to scan for completed messages." } ], "x-permissions": [ "agent:read" ] } }, "/linc/v1/sessions/{id}/rpc": { "post": { "tags": [ "Agents/Linc" ], "summary": "Send native Pi RPC command", "description": "Forwards a native Pi/Linc RPC command object to the sandbox-local Linc bridge unchanged. The route returns after Pi accepts or rejects the command; native events are read through the events endpoint.", "operationId": "sendLincSessionRpcV1", "responses": { "202": { "description": "Native Pi RPC response, or pending acknowledgement for a deduped prompt" }, "400": { "description": "Invalid payload", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Linc session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Linc session is not active, or the runtime is terminally stopped (data.code: linc_runtime_stopped, data.retryable: false)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "410": { "description": "Linc runtime has expired and its saved state is gone (data.code: linc_runtime_expired, data.retryable: false); events stay readable", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "502": { "description": "Linc runtime command or bridge RPC failed (data.retryable: true)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Linc runtime is waking or temporarily unreachable (data.code: linc_runtime_unreachable, data.retryable: true) — retry with the same command id", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Linc session ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "additionalProperties": true, "properties": { "type": { "type": "string", "description": "Native Pi/Linc RPC command type. Prompt commands also require a string id for idempotency." }, "id": { "type": "string", "description": "Command idempotency key. Required when type is prompt." } } } } } }, "x-permissions": [ "agent:write" ] } }, "/linc/v1/sessions/{id}/scope": { "put": { "tags": [ "Agents/Linc" ], "summary": "Replace a persistent Linc conversation scope", "description": "Stops the conversation worker, applies a newly authorized object scope, revokes its prior managed credential, and resumes the same native conversation in its existing workspace.", "operationId": "replaceLincSessionScopeV1", "responses": { "200": { "description": "Conversation scope replaced and runtime resumed" }, "400": { "description": "Invalid scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Session, vault, or object not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "Session is not a resumable persistent workspace conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "The conversation was stopped safely but could not be resumed", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "required": [ "vaultIds" ] }, { "required": [ "vaultScopes" ] } ], "properties": { "vaultIds": { "type": "array", "items": { "type": "string" }, "description": "Legacy whole-vault scope. Mutually exclusive with vaultScopes." }, "vaultScopes": { "type": "array", "description": "Authoritative object allowlist for the next and later turns.", "items": { "type": "object", "required": [ "vaultId", "objectIds" ], "properties": { "vaultId": { "type": "string" }, "objectIds": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "x-permissions": [ "agent:write" ] } }, "/linc/v1/sessions/{id}/state": { "get": { "tags": [ "Agents/Linc" ], "summary": "Get native Linc session state", "operationId": "getLincSessionStateV1", "responses": { "200": { "description": "Linc session state. Ended sessions answer 200 with session.status \"ended\" (bridge/rpc null) rather than 404. A verified running sandbox with a temporarily unavailable bridge answers 200 with bridge/rpc null and bridgeStatus \"unavailable\"; retry the prompt RPC with the same command id to recover the existing runtime." }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "No agent access or Linc runtime disabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "Linc session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } }, "503": { "description": "Live runtime state is temporarily unavailable (data.code: linc_runtime_state_unavailable, data.retryable: true)", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "agent:read" ] } }, "/llm/config": { "get": { "tags": [ "LLMs" ], "summary": "Get LLM configuration", "description": "Retrieves the AI Gateway configuration including all available language models and their specifications. This endpoint returns model information compatible with the Vercel AI SDK Gateway format, making it easy to integrate with existing AI applications.\n\nUse this endpoint to:\n- Discover available language models\n- Get model specifications and pricing\n- Configure AI SDK clients\n- Build model selection interfaces", "operationId": "getLlmConfig", "responses": { "200": { "description": "AI Gateway configuration with available models", "content": { "application/json": { "schema": { "type": "object", "properties": { "models": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique model identifier" }, "name": { "type": "string", "description": "Human-readable model name" }, "modelType": { "type": "string", "description": "Type of model (e.g., language, embedding)" }, "description": { "type": "string", "description": "Model description and capabilities" }, "pricing": { "type": "object", "description": "Pricing information for the model" }, "specification": { "type": "object", "description": "Technical specifications and limits" } }, "required": [ "id", "name", "modelType" ] } } }, "required": [ "models" ] }, "example": { "models": [ { "id": "gpt-4", "name": "GPT-4", "modelType": "language", "description": "Most capable GPT-4 model for complex legal analysis", "pricing": { "input": 0.03, "output": 0.06, "currency": "USD", "unit": "1K tokens" } }, { "id": "claude-3-opus", "name": "Claude 3 Opus", "modelType": "language", "description": "Anthropic's most powerful model for legal reasoning" }, { "id": "text-embedding-3-large", "name": "Text Embedding 3 Large", "modelType": "embedding", "description": "High-performance embeddings for semantic search" } ] } } } }, "401": { "description": "Authentication failed - invalid or missing API key" } }, "x-permissions": [ "llm:read" ] } }, "/llm/v1/chat/completions": { "post": { "tags": [ "LLMs" ], "summary": "Chat completions", "description": "Create a completion for the provided prompt and parameters. Compatible with OpenAI's chat completions API. Supports 40+ models including GPT-4, Claude, Gemini, and CaseMark legal AI models. Includes streaming support, token counting, and usage tracking.", "operationId": "createChatCompletion", "responses": { "200": { "description": "Successful completion response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the completion" }, "object": { "type": "string", "example": "chat.completion" }, "created": { "type": "integer", "description": "Unix timestamp of completion creation" }, "model": { "type": "string", "description": "Model used for completion" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "message": { "type": "object", "properties": { "role": { "type": "string" }, "content": { "type": "string" } } }, "finish_reason": { "type": "string" } } } }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "completion_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" }, "cost": { "type": "number", "description": "Cost in USD" } } } } } } } }, "400": { "description": "Invalid request parameters or unsupported model capabilities (data.code: unsupported_model_input, data.retryable: false). CaseMark chat models and Lightning aliases validate input types across the complete message history and reject non-text output before dispatch. Rejections include safe data.inputTypes or data.outputTypes lists." }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "API key does not have access to LLM service" } }, "parameters": [ { "name": "ai-reporting-user", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Stable internal user or customer identifier for AI Gateway cost reporting." }, { "name": "ai-reporting-tags", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Comma-separated AI Gateway reporting tags. At most 10 unique tags, each 1–64 characters." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "model": { "type": "string", "description": "Model to use for completion. Defaults to casemark/core-large if not specified", "example": "casemark/core-large" }, "messages": { "type": "array", "description": "List of messages comprising the conversation", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant" ], "description": "The role of the message author" }, "content": { "type": "string", "description": "The contents of the message" } } } }, "max_tokens": { "type": "integer", "description": "Maximum number of tokens to generate", "example": 1000 }, "temperature": { "type": "number", "description": "Sampling temperature between 0 and 2", "example": 0.7 }, "stream": { "type": "boolean", "description": "Whether to stream back partial progress", "example": false }, "casemark_show_reasoning": { "type": "boolean", "description": "CaseMark-only: controls whether reasoning fields appear in responses. Defaults to false (suppressed) for most CaseMark models; defaults to true for casemark/core-potassium.", "example": false }, "top_p": { "type": "number", "description": "Nucleus sampling parameter" }, "frequency_penalty": { "type": "number", "description": "Frequency penalty parameter" }, "presence_penalty": { "type": "number", "description": "Presence penalty parameter" } } } } } }, "x-permissions": [ "llm", "chat" ] } }, "/llm/v1/embeddings": { "post": { "tags": [ "LLMs" ], "summary": "Create embeddings", "description": "Create vector embeddings from text using OpenAI-compatible models. Perfect for semantic search, document similarity, and building RAG systems for legal documents.", "operationId": "createEmbeddings", "responses": { "200": { "description": "Embeddings created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "example": "list" }, "data": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string", "example": "embedding" }, "index": { "type": "integer" }, "embedding": { "type": "array", "items": { "type": "number" } } } } }, "model": { "type": "string" }, "usage": { "type": "object", "properties": { "prompt_tokens": { "type": "integer" }, "total_tokens": { "type": "integer" } } } } }, "example": { "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [ 0.0023, -0.0087, 0.0156 ] } ], "model": "text-embedding-ada-002", "usage": { "prompt_tokens": 12, "total_tokens": 12 } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to LLM service" }, "502": { "description": "Upstream embedding provider failed" } }, "requestBody": { "description": "Embedding request configuration", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input", "model" ], "properties": { "input": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Text or array of texts to create embeddings for" }, "model": { "type": "string", "description": "Embedding model to use (e.g., text-embedding-ada-002, text-embedding-3-small)" }, "encoding_format": { "type": "string", "enum": [ "float", "base64" ], "default": "float", "description": "Format for returned embeddings" }, "dimensions": { "type": "integer", "description": "Number of dimensions for the embeddings (model-specific)" }, "user": { "type": "string", "description": "Unique identifier for the end-user" } } } } } }, "x-permissions": [ "chat", "llm" ] } }, "/llm/v1/health": { "get": { "tags": [ "LLMs" ], "summary": "Health check", "description": "Unauthenticated health check for the LLM service.", "operationId": "getLLMHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "llm" } } } } } } }, "/llm/v1/models": { "get": { "tags": [ "LLMs" ], "summary": "List available language models", "description": "Retrieve the curated list of available models: OpenAI, Anthropic, and Google models plus Case.dev's specialized CaseMark legal models. Returns OpenAI-compatible model metadata with pricing information.\n\nThis endpoint is compatible with OpenAI's models API format, making it easy to integrate with existing applications.", "operationId": "listModels", "responses": { "200": { "description": "Successfully retrieved models list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique model identifier" }, "object": { "type": "string", "description": "Object type, always 'model'" }, "created": { "type": "integer", "description": "Unix timestamp of model creation" }, "owned_by": { "type": "string", "description": "Model provider (openai, anthropic, google, casemark, etc.)" }, "pricing": { "type": "object", "properties": { "input": { "type": "string", "description": "Input token price per token" }, "output": { "type": "string", "description": "Output token price per token" }, "input_cache_read": { "type": "string", "description": "Cache read price per token (if supported)" } } } } } }, "object": { "type": "string", "description": "Response object type, always 'list'" } } }, "example": { "data": [ { "id": "casemark/contract-analyzer", "object": "model", "created": 1678886400, "owned_by": "casemark", "pricing": { "input": "0.000001000", "output": "0.000003000" } }, { "id": "gpt-4o", "object": "model", "created": 1678886400, "owned_by": "openai", "pricing": { "input": "0.000005000", "output": "0.000015000" } }, { "id": "claude-3-5-sonnet-20241022", "object": "model", "created": 1678886400, "owned_by": "anthropic", "pricing": { "input": "0.000003000", "output": "0.000015000", "input_cache_read": "0.000000300" } } ], "object": "list" } } } }, "401": { "description": "Invalid or missing API key" }, "502": { "description": "AI Gateway returned invalid response" } } } }, "/matters/v1": { "get": { "tags": [ "Matters" ], "summary": "List matters", "description": "List matters for the authenticated organization, newest update first. Pagination is opt-in: pass `limit` (1-200) to receive a bounded page, then replay `pagination.next_cursor` as `?cursor=` while `pagination.has_more` is true. Cursors are opaque and are only valid for the exact filter set they were issued under. A request with neither `limit` nor `cursor` still returns every matter, and `pagination.limit` is null. That default will become a bounded page in a future release — paginate now to avoid the change.", "operationId": "listMattersV1", "responses": { "200": { "description": "Matter list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "nullable": true }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "Invalid cursor or limit" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" } }, "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "matter_type", "in": "query", "schema": { "type": "string" } }, { "name": "practice_area", "in": "query", "schema": { "type": "string" } }, { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Matters per page (1-200). Omit to receive every matter. Supplying a cursor without a limit uses 50." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor from `pagination.next_cursor` of the previous page. Must be replayed with the same filters that produced it." } ], "x-permissions": [ "all", "matters" ] }, "post": { "tags": [ "Matters" ], "summary": "Create matter", "description": "Create a new legal matter and optionally link an existing primary vault.", "operationId": "createMatterV1", "responses": { "201": { "description": "Matter created" }, "400": { "description": "Invalid matter payload" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Organization or responsible attorney not found" }, "409": { "description": "display_id already exists" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "display_id": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "intake", "open", "pending", "closed", "archived" ] }, "matter_type": { "type": "string" }, "practice_area": { "type": "string" }, "subtype": { "type": "string" }, "client_party_id": { "type": "string", "nullable": true }, "client_name": { "type": "string" }, "responsible_attorney_id": { "type": "string" }, "jurisdiction": { "type": "object", "additionalProperties": true }, "important_dates": { "type": "object", "additionalProperties": true }, "billing": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "custom_fields": { "type": "object", "additionalProperties": true }, "vault_id": { "type": "string" }, "vault": { "type": "object", "properties": { "description": { "type": "string" }, "enableIndexing": { "type": "boolean" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } }, "x-permissions": [ "all" ] } }, "/matters/v1/{id}": { "get": { "tags": [ "Matters" ], "summary": "Get matter", "description": "Get a single matter by ID.", "operationId": "getMatterV1", "responses": { "200": { "description": "Matter record" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Matter not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] }, "patch": { "tags": [ "Matters" ], "summary": "Update matter", "description": "Update mutable matter fields.", "operationId": "updateMatterV1", "responses": { "200": { "description": "Matter updated" }, "400": { "description": "Invalid matter payload" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Matter or attorney not found" }, "409": { "description": "display_id already exists" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "display_id": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "intake", "open", "pending", "closed", "archived" ] }, "matter_type": { "type": "string" }, "practice_area": { "type": "string" }, "subtype": { "type": "string" }, "client_party_id": { "type": "string", "nullable": true }, "client_name": { "type": "string" }, "responsible_attorney_id": { "type": "string" }, "jurisdiction": { "type": "object", "additionalProperties": true }, "important_dates": { "type": "object", "additionalProperties": true }, "billing": { "type": "object", "additionalProperties": true }, "metadata": { "type": "object", "additionalProperties": true }, "custom_fields": { "type": "object", "additionalProperties": true }, "archived_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "x-permissions": [ "all", "matters" ] }, "delete": { "tags": [ "Matters" ], "summary": "Purge a Matter", "description": "Queues a durable, idempotent purge of a Matter and all linked live content. Use matter purge webhooks for status changes; the inspection route is intended for manual diagnostics only.", "operationId": "deleteMatterV1", "responses": { "202": { "description": "Purge queued, already active, or already completed", "content": { "application/json": { "schema": { "type": "object", "required": [ "purge_id", "status", "attempt", "matter_id", "vault_id", "workflow_id" ], "properties": { "purge_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "failed", "completed" ] }, "attempt": { "type": "integer" }, "matter_id": { "type": "string" }, "vault_id": { "type": "string" }, "workflow_id": { "type": "string", "nullable": true }, "terminal_event_id": { "type": "string", "nullable": true, "description": "Stable ID of the failed or completed terminal webhook event" }, "failure_code": { "type": "string", "nullable": true }, "requested_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "counts": { "type": "object", "properties": { "objects": { "type": "integer" }, "transcriptions": { "type": "integer" }, "sessions": { "type": "integer" }, "chats": { "type": "integer" } } } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "Matter write scope required" }, "404": { "description": "Matter not found" }, "409": { "description": "Matter purge requires a dedicated Vault" }, "503": { "description": "Purge workflow could not be started; the receipt is retryable" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/content-purges": { "post": { "tags": [ "Matters" ], "summary": "Purge selected Matter content", "description": "Queues an idempotent hard deletion of explicitly owned content while preserving the Matter, Vault, and unrelated content. Use unified matter.content_purge webhooks for completion, not polling.", "operationId": "createMatterContentPurgeV1", "responses": { "202": { "description": "Queued, active, or completed receipt", "content": { "application/json": { "schema": { "type": "object", "required": [ "purge_id", "request_id", "attempt", "status", "matter_id", "vault_id", "workflow_id" ], "properties": { "purge_id": { "type": "string" }, "request_id": { "type": "string" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "failed", "completed" ] }, "matter_id": { "type": "string" }, "vault_id": { "type": "string" }, "workflow_id": { "type": "string", "nullable": true }, "terminal_event_id": { "type": "string", "nullable": true }, "failure_code": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "requested_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "400": { "description": "Invalid request or target count" }, "401": { "description": "Invalid API key" }, "403": { "description": "Matter write scope required" }, "404": { "description": "Owned Matter or target not found" }, "409": { "description": "Content in use, already claimed, or request ID conflict" }, "503": { "description": "Durable dispatch remains pending; reuse the same request ID" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id" ], "additionalProperties": false, "properties": { "request_id": { "type": "string", "description": "Stable caller idempotency ID; cannot be reused with different targets." }, "object_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "session_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "work_item_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "transcription_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/events/subscriptions": { "get": { "tags": [ "Matters" ], "summary": "List matter webhook subscriptions", "description": "Lists webhook subscriptions configured for a matter.", "operationId": "listMatterEventSubscriptionsV1", "responses": { "200": { "description": "Matter subscriptions retrieved successfully" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Matter not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] }, "post": { "tags": [ "Matters" ], "summary": "Create matter webhook subscription", "description": "Creates a webhook subscription for matter and work-item events.", "operationId": "createMatterEventSubscriptionV1", "responses": { "201": { "description": "Matter webhook subscription created successfully" }, "400": { "description": "Webhook payload or idempotency key is invalid" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Matter not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Reusing a key for this Matter updates and returns the same webhook subscription." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "callbackUrl" ], "properties": { "callbackUrl": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "signingSecret": { "type": "string" } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/events/subscriptions/{subscriptionId}": { "delete": { "tags": [ "Matters" ], "summary": "Delete matter webhook subscription", "description": "Deactivates a matter webhook subscription.", "operationId": "deleteMatterEventSubscriptionV1", "responses": { "200": { "description": "Subscription deleted" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Matter or subscription not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/log": { "get": { "tags": [ "Matters" ], "summary": "List matter log entries", "description": "List the operational history for a matter.", "operationId": "listMatterLogEntriesV1", "responses": { "200": { "description": "Matter log entries" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Matter not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Maximum number of log entries to return (max 200)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of log entries to skip for pagination" }, { "name": "scope", "in": "query", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "description": "Filter by scope: matter, work_item, execution, sharing, all" }, { "name": "event_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by exact event type" }, { "name": "work_item_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by work item ID" }, { "name": "actor_type", "in": "query", "schema": { "type": "string" }, "description": "Filter by actor type" }, { "name": "actor_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by actor ID" }, { "name": "start_time", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of time range (ISO 8601)" }, { "name": "end_time", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of time range (ISO 8601)" } ], "x-permissions": [ "all", "matters" ] }, "post": { "tags": [ "Matters" ], "summary": "Create matter log entry", "description": "Append a manual operational note or event to a matter log.", "operationId": "createMatterLogEntryV1", "responses": { "201": { "description": "Matter log entry created" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "summary" ], "properties": { "event_type": { "type": "string" }, "summary": { "type": "string" }, "details": { "type": "object", "additionalProperties": true }, "work_item_id": { "type": "string" } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/log/export": { "post": { "tags": [ "Matters" ], "summary": "Export matter log entries", "description": "Bulk export matter log entries for audits, visibility, and eval pipelines. Supports json, csv, tsv, and jsonl. Limited to 10,000 entries per request.", "operationId": "exportMatterLogEntriesV1", "responses": { "200": { "description": "Exported matter log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON (one log entry per line)" } }, "text/csv": { "schema": { "type": "string", "description": "CSV export of matter log entries" } }, "text/tab-separated-values": { "schema": { "type": "string", "description": "TSV export of matter log entries" } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Matter not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Filter by scope: matter, work_item, execution, sharing, all" }, "event_type": { "type": "string", "description": "Filter by exact event type" }, "work_item_id": { "type": "string", "description": "Filter by work item ID" }, "actor_type": { "type": "string", "description": "Filter by actor type" }, "actor_id": { "type": "string", "description": "Filter by actor ID" }, "start_time": { "type": "string", "format": "date-time", "description": "Start of time range (ISO 8601)" }, "end_time": { "type": "string", "format": "date-time", "description": "End of time range (ISO 8601)" }, "format": { "type": "string", "enum": [ "json", "jsonl", "csv", "tsv" ], "description": "Export format. Defaults to jsonl." } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/parties": { "get": { "tags": [ "Matters" ], "summary": "List matter parties", "description": "List parties attached to a matter.", "operationId": "listMatterPartiesV1", "responses": { "200": { "description": "Matter parties" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] }, "post": { "tags": [ "Matters" ], "summary": "Attach party to matter", "description": "Attach a reusable party to a matter with a matter-specific role.", "operationId": "attachMatterPartyV1", "responses": { "201": { "description": "Matter party attached" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "party_id", "role" ], "properties": { "party_id": { "type": "string" }, "role": { "type": "string", "enum": [ "client", "prospect", "opposing_party", "opposing_counsel", "co_counsel", "judge", "expert", "witness", "vendor", "insurer", "other" ] }, "is_primary": { "type": "boolean" }, "notes": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true }, "custom_fields": { "type": "object", "additionalProperties": true, "nullable": true }, "set_as_client": { "type": "boolean" } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/shares": { "get": { "tags": [ "Matters" ], "summary": "List matter shares", "description": "List cross-org shares for a matter. Owner only.", "operationId": "listMatterSharesV1", "responses": { "200": { "description": "Matter shares" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] }, "post": { "tags": [ "Matters" ], "summary": "Create matter share", "description": "Grant another organization scoped access to this matter and its primary vault.", "operationId": "createMatterShareV1", "responses": { "201": { "description": "Matter share created or updated" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_org_id" ], "properties": { "target_org_id": { "type": "string" }, "permission": { "type": "string", "enum": [ "read", "edit" ], "default": "read" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/shares/{shareId}": { "delete": { "tags": [ "Matters" ], "summary": "Delete matter share", "description": "Revoke a matter share and its linked vault share.", "operationId": "deleteMatterShareV1", "responses": { "200": { "description": "Matter share deleted" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/work-items": { "get": { "tags": [ "Matters" ], "summary": "List matter work items", "description": "List active work items for a matter, newest update first. Pagination is opt-in: pass `limit` (1-200) to receive a bounded page, then replay `pagination.next_cursor` as `?cursor=` while `pagination.has_more` is true. A request with neither `limit` nor `cursor` still returns every work item, and `pagination.limit` is null. That default will become a bounded page in a future release — paginate now to avoid the change.", "operationId": "listMatterWorkItemsV1", "responses": { "200": { "description": "Matter work items", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "nullable": true }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "Invalid cursor or limit" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "assignee_id", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Work items per page (1-200). Omit to receive every work item. Supplying a cursor without a limit uses 50." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor from `pagination.next_cursor` of the previous page. Must be replayed with the same filters that produced it." } ], "x-permissions": [ "all", "matters" ] }, "post": { "tags": [ "Matters" ], "summary": "Create work item", "description": "Create an active work item on a matter.", "operationId": "createMatterWorkItemV1", "responses": { "201": { "description": "Work item created" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "task", "deadline", "review", "filing", "communication", "research", "drafting", "collection", "intake" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_id": { "type": "string" }, "instructions": { "type": "string" }, "exit_criteria": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "due_at": { "type": "string", "format": "date-time" } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/work-items/{workItemId}": { "get": { "tags": [ "Matters" ], "summary": "Get work item", "description": "Get a single work item for a matter.", "operationId": "getMatterWorkItemV1", "responses": { "200": { "description": "Work item" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workItemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] }, "patch": { "tags": [ "Matters" ], "summary": "Update work item", "description": "Update a matter work item.", "operationId": "updateMatterWorkItemV1", "responses": { "200": { "description": "Work item updated" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workItemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "enum": [ "task", "deadline", "review", "filing", "communication", "research", "drafting", "collection", "intake" ] }, "status": { "type": "string", "enum": [ "draft", "queued", "in_progress", "blocked", "in_review", "awaiting_human", "done", "canceled" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assignee_id": { "type": "string", "nullable": true }, "instructions": { "type": "string", "nullable": true }, "exit_criteria": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/{id}/work-items/{workItemId}/decision": { "post": { "tags": [ "Matters" ], "summary": "Make work item decision", "description": "Approve or block a work item.", "operationId": "decideMatterWorkItemV1", "responses": { "200": { "description": "Decision applied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workItemId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "block" ] }, "reason": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "x-permissions": [ "all", "matters" ] } }, "/matters/v1/agent-types": { "get": { "tags": [ "Matters" ], "summary": "List agent types", "description": "List reusable agent roles for the authenticated organization.", "operationId": "listMatterAgentTypesV1", "responses": { "200": { "description": "Agent types" } }, "parameters": [ { "name": "active", "in": "query", "schema": { "type": "boolean" } } ], "x-permissions": [ "all" ] }, "post": { "tags": [ "Matters" ], "summary": "Create agent type", "description": "Create a reusable agent role for legal matter orchestration.", "operationId": "createMatterAgentTypeV1", "responses": { "201": { "description": "Agent type created" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "instructions" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "instructions": { "type": "string" }, "model": { "type": "string" }, "enabled_tools": { "type": "array", "items": { "type": "string" } }, "disabled_tools": { "type": "array", "items": { "type": "string" } }, "skill_refs": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object", "additionalProperties": true }, "is_default": { "type": "boolean" }, "is_active": { "type": "boolean" } } } } } }, "x-permissions": [ "all" ] } }, "/matters/v1/content-purges/{purgeId}": { "get": { "tags": [ "Matters" ], "summary": "Inspect a content purge", "description": "Owner-only receipt for operator diagnostics. Integrations must use unified content-purge webhooks rather than polling.", "operationId": "retrieveMatterContentPurgeV1", "responses": { "200": { "description": "Content-free purge receipt", "content": { "application/json": { "schema": { "type": "object", "required": [ "purge_id", "request_id", "attempt", "status", "matter_id", "vault_id", "workflow_id" ], "properties": { "purge_id": { "type": "string" }, "request_id": { "type": "string" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "failed", "completed" ] }, "matter_id": { "type": "string" }, "vault_id": { "type": "string" }, "workflow_id": { "type": "string", "nullable": true }, "terminal_event_id": { "type": "string", "nullable": true }, "failure_code": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "requested_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "Matter read scope required" }, "404": { "description": "Owned purge not found" } }, "parameters": [ { "name": "purgeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] } }, "/matters/v1/parties": { "get": { "tags": [ "Matters" ], "summary": "List parties", "description": "List reusable legal parties for the authenticated organization, newest update first. Pagination is opt-in: pass `limit` (1-200) to receive a bounded page, then replay `pagination.next_cursor` as `?cursor=` while `pagination.has_more` is true. A request with neither `limit` nor `cursor` still returns every party, and `pagination.limit` is null. That default will become a bounded page in a future release — paginate now to avoid the change.", "operationId": "listMatterPartyEntitiesV1", "responses": { "200": { "description": "Party list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "nullable": true }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "Invalid cursor or limit" } }, "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "person", "organization" ] } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Parties per page (1-200). Omit to receive every party. Supplying a cursor without a limit uses 50." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor from `pagination.next_cursor` of the previous page. Must be replayed with the same filters that produced it." } ], "x-permissions": [ "all" ] }, "post": { "tags": [ "Matters" ], "summary": "Create party", "description": "Create a reusable legal party for the authenticated organization.", "operationId": "createMatterPartyEntityV1", "responses": { "201": { "description": "Party created" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "type": { "type": "string", "enum": [ "person", "organization" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "addresses": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "metadata": { "type": "object", "additionalProperties": true }, "custom_fields": { "type": "object", "additionalProperties": true, "nullable": true }, "notes": { "type": "string", "nullable": true } } } } } }, "x-permissions": [ "all" ] } }, "/matters/v1/parties/{partyId}": { "get": { "tags": [ "Matters" ], "summary": "Get party", "description": "Get a reusable legal party by ID.", "operationId": "getMatterPartyEntityV1", "responses": { "200": { "description": "Party record" } }, "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all" ] }, "patch": { "tags": [ "Matters" ], "summary": "Update party", "description": "Update a reusable legal party.", "operationId": "updateMatterPartyEntityV1", "responses": { "200": { "description": "Party updated" } }, "parameters": [ { "name": "partyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all" ] } }, "/matters/v1/purges/{purgeId}": { "get": { "tags": [ "Matters" ], "summary": "Inspect a Matter purge", "description": "Returns a Matter purge receipt for manual diagnostics. Integrations should subscribe to Matter purge webhooks rather than polling this route.", "operationId": "retrieveMatterPurgeV1", "responses": { "200": { "description": "Matter purge receipt", "content": { "application/json": { "schema": { "type": "object", "required": [ "purge_id", "status", "attempt", "matter_id", "vault_id", "workflow_id" ], "properties": { "purge_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "in_progress", "failed", "completed" ] }, "attempt": { "type": "integer" }, "matter_id": { "type": "string" }, "vault_id": { "type": "string" }, "workflow_id": { "type": "string", "nullable": true }, "terminal_event_id": { "type": "string", "nullable": true, "description": "Stable ID of the failed or completed terminal webhook event" }, "failure_code": { "type": "string", "nullable": true }, "requested_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "failed_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "counts": { "type": "object", "properties": { "objects": { "type": "integer" }, "transcriptions": { "type": "integer" }, "sessions": { "type": "integer" }, "chats": { "type": "integer" } } } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "Matter read scope required" }, "404": { "description": "Matter purge not found" } }, "parameters": [ { "name": "purgeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all", "matters" ] } }, "/matters/v1/types": { "get": { "tags": [ "Matters" ], "summary": "List matter types", "description": "List matter types for the authenticated organization.", "operationId": "listMatterTypesV1", "responses": { "200": { "description": "Matter types" } }, "parameters": [ { "name": "active", "in": "query", "schema": { "type": "boolean" } } ], "x-permissions": [ "all" ] }, "post": { "tags": [ "Matters" ], "summary": "Create matter type", "description": "Create a matter type with plain-English operating instructions and seeded work.", "operationId": "createMatterTypeV1", "responses": { "201": { "description": "Matter type created" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "instructions": { "type": "string" }, "default_agent_type_id": { "type": "string" }, "review_agent_type_id": { "type": "string" }, "orchestration_mode": { "type": "string", "enum": [ "auto", "human" ] }, "intake_requirements": { "type": "array", "items": { "type": "string" } }, "review_criteria": { "type": "array", "items": { "type": "string" } }, "exit_criteria": { "type": "array", "items": { "type": "string" } }, "skill_refs": { "type": "array", "items": { "type": "string" } }, "default_metadata": { "type": "object", "additionalProperties": true }, "default_work_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "is_active": { "type": "boolean" } } } } } }, "x-permissions": [ "all" ] } }, "/matters/v1/types/{id}": { "get": { "tags": [ "Matters" ], "summary": "Get matter type", "description": "Get a single matter type.", "operationId": "getMatterTypeV1", "responses": { "200": { "description": "Matter type" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "all" ] }, "patch": { "tags": [ "Matters" ], "summary": "Update matter type", "description": "Update a matter type.", "operationId": "updateMatterTypeV1", "responses": { "200": { "description": "Matter type updated" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string", "nullable": true }, "instructions": { "type": "string", "nullable": true }, "default_agent_type_id": { "type": "string", "nullable": true }, "review_agent_type_id": { "type": "string", "nullable": true }, "orchestration_mode": { "type": "string", "enum": [ "auto", "human" ] }, "intake_requirements": { "type": "array", "items": { "type": "string" } }, "review_criteria": { "type": "array", "items": { "type": "string" } }, "exit_criteria": { "type": "array", "items": { "type": "string" } }, "skill_refs": { "type": "array", "items": { "type": "string" } }, "default_metadata": { "type": "object", "additionalProperties": true }, "default_work_items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "is_active": { "type": "boolean" } } } } } }, "x-permissions": [ "all" ] } }, "/media/v1/clips": { "post": { "tags": [ "Media" ], "summary": "Create a captioned media clip", "operationId": "createMediaClip", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "x-permissions": [ "vault" ] } }, "/media/v1/clips/{id}": { "get": { "tags": [ "Media" ], "summary": "Get media clip job", "operationId": "getMediaClip", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "vault" ] } }, "/media/v1/health": { "get": { "tags": [ "Media" ], "summary": "Health check", "description": "Unauthenticated health check for the Media service.", "operationId": "getMediaHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "media" } } } } } } }, "/media/v1/transcripts/retrieve": { "post": { "tags": [ "Media" ], "summary": "Retrieve transcript text", "description": "Retrieves the full transcript text for a vault transcript object or an audio/video source object with a completed transcription job. When object_id is a source media object, access to that source object grants access to its generated transcript artifact.", "operationId": "retrieveMediaTranscriptText", "responses": { "200": { "description": "Transcript text retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "text", "vault_id", "object_id" ], "properties": { "status": { "type": "string", "enum": [ "completed" ] }, "text": { "type": "string", "description": "Full transcript text." }, "vault_id": { "type": "string" }, "object_id": { "type": "string", "description": "Requested object ID." }, "source_object_id": { "type": "string", "description": "Source media object ID when known." }, "transcript_object_id": { "type": "string", "description": "Transcript object ID when known." }, "transcription_job_id": { "type": "string", "description": "Transcription job ID when known." }, "filename": { "type": "string" }, "word_count": { "type": "integer" }, "confidence": { "type": "integer" }, "audio_duration": { "type": "integer" } } } } } }, "400": { "description": "Missing parameters or object is not transcript media." }, "401": { "description": "Invalid API key." }, "403": { "description": "API key lacks vault access or object scope." }, "404": { "description": "Vault, object, or completed transcript not found." }, "409": { "description": "Transcript exists but is still processing." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vault_id", "object_id" ], "properties": { "vault_id": { "type": "string", "description": "Vault ID containing the source media or transcript object." }, "object_id": { "type": "string", "description": "Object ID for either the source audio/video file or transcript artifact." }, "transcript": { "type": "object", "description": "Alternative nested transcript object reference.", "properties": { "vault_id": { "type": "string" }, "object_id": { "type": "string" } } } } } } } }, "x-permissions": [ "vault" ] } }, "/media/v1/transcripts/search": { "post": { "tags": [ "Media" ], "summary": "Search transcript words", "operationId": "searchMediaTranscriptWords", "responses": { "200": { "description": "Success" }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal Server Error" } }, "x-permissions": [ "vault" ] } }, "/memory/v1": { "get": { "tags": [ "Memory" ], "summary": "List memories", "description": "List all memories with optional filtering by tags and category.", "operationId": "listMemories", "responses": { "200": { "description": "List of memories", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "memory": { "type": "string" }, "tags": { "type": "object" }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer", "description": "Total count matching filters" } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Memory service" } }, "parameters": [ { "name": "tag_1", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_1" }, { "name": "tag_2", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_2" }, { "name": "tag_3", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_3" }, { "name": "tag_4", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_4" }, { "name": "tag_5", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_5" }, { "name": "tag_6", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_6" }, { "name": "tag_7", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_7" }, { "name": "tag_8", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_8" }, { "name": "tag_9", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_9" }, { "name": "tag_10", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_10" }, { "name": "tag_11", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_11" }, { "name": "tag_12", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_12" }, { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by category" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Pagination offset" } ], "x-permissions": [ "memory:read" ] }, "post": { "tags": [ "Memory" ], "summary": "Add memory", "description": "Store memories from conversation messages. Automatically extracts facts and handles deduplication.\n\nUse tag_1 through tag_12 for filtering - these are generic indexed fields you can use for any purpose:\n- Legal app: tag_1=client_id, tag_2=matter_id\n- Healthcare: tag_1=patient_id, tag_2=encounter_id\n- E-commerce: tag_1=customer_id, tag_2=order_id", "operationId": "addMemory", "responses": { "200": { "description": "Memories added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "memory": { "type": "string", "description": "Extracted memory text" }, "event": { "type": "string", "enum": [ "ADD", "UPDATE", "DELETE", "NONE" ], "description": "What happened to this memory" } } } } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Memory service" }, "500": { "description": "Memory service error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "description": "Conversation messages to extract memories from", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant", "system" ], "description": "Message role" }, "content": { "type": "string", "description": "Message content" } } } }, "tag_1": { "type": "string", "description": "Generic indexed filter field 1 (you decide what it means)" }, "tag_2": { "type": "string", "description": "Generic indexed filter field 2" }, "tag_3": { "type": "string", "description": "Generic indexed filter field 3" }, "tag_4": { "type": "string", "description": "Generic indexed filter field 4" }, "tag_5": { "type": "string", "description": "Generic indexed filter field 5" }, "tag_6": { "type": "string", "description": "Generic indexed filter field 6" }, "tag_7": { "type": "string", "description": "Generic indexed filter field 7" }, "tag_8": { "type": "string", "description": "Generic indexed filter field 8" }, "tag_9": { "type": "string", "description": "Generic indexed filter field 9" }, "tag_10": { "type": "string", "description": "Generic indexed filter field 10" }, "tag_11": { "type": "string", "description": "Generic indexed filter field 11" }, "tag_12": { "type": "string", "description": "Generic indexed filter field 12" }, "category": { "type": "string", "description": "Custom category (e.g., \"fact\", \"preference\", \"deadline\")" }, "metadata": { "type": "object", "description": "Additional metadata (not indexed)", "additionalProperties": true }, "infer": { "type": "boolean", "default": true, "description": "Whether to extract facts from messages (default: true)" }, "extraction_prompt": { "type": "string", "description": "Optional custom prompt for fact extraction" } } } } } }, "x-permissions": [ "memory:write" ] }, "delete": { "tags": [ "Memory" ], "summary": "Bulk delete memories", "description": "Delete multiple memories matching tag filter criteria. CAUTION: This will delete all matching memories for your organization.", "operationId": "deleteMemories", "responses": { "200": { "description": "Memories deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "Number of memories deleted" } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Memory service" }, "500": { "description": "Memory service error" } }, "parameters": [ { "name": "tag_1", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_1" }, { "name": "tag_2", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_2" }, { "name": "tag_3", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_3" }, { "name": "tag_4", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_4" }, { "name": "tag_5", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_5" }, { "name": "tag_6", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_6" }, { "name": "tag_7", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_7" }, { "name": "tag_8", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_8" }, { "name": "tag_9", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_9" }, { "name": "tag_10", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_10" }, { "name": "tag_11", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_11" }, { "name": "tag_12", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag_12" } ], "x-permissions": [ "memory:write" ] } }, "/memory/v1/{id}": { "get": { "tags": [ "Memory" ], "summary": "Get memory", "description": "Retrieve a single memory by its ID.", "operationId": "getMemory", "responses": { "200": { "description": "Memory details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "memory": { "type": "string", "description": "Memory content" }, "metadata": { "type": "object", "description": "Memory metadata" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Memory service" }, "404": { "description": "Memory not found" }, "500": { "description": "Memory service error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Memory ID" } ], "x-permissions": [ "memory:read" ] }, "delete": { "tags": [ "Memory" ], "summary": "Delete memory", "description": "Delete a single memory by its ID.", "operationId": "deleteMemory", "responses": { "200": { "description": "Memory deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Memory service" }, "404": { "description": "Memory not found" }, "500": { "description": "Memory service error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Memory ID" } ], "x-permissions": [ "memory:write" ] } }, "/memory/v1/health": { "get": { "tags": [ "Memory" ], "summary": "Health check", "description": "Check if the Memory service is available.", "operationId": "memoryHealth", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "503": { "description": "Service is unavailable" } } } }, "/memory/v1/search": { "post": { "tags": [ "Memory" ], "summary": "Search memories", "description": "Search memories using semantic similarity. Filter by tag fields to narrow results.\n\nUse tag_1 through tag_12 for filtering - these are generic indexed fields you define:\n- Legal app: tag_1=client_id, tag_2=matter_id\n- Healthcare: tag_1=patient_id, tag_2=encounter_id", "operationId": "searchMemory", "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Memory ID" }, "memory": { "type": "string", "description": "Memory content" }, "score": { "type": "number", "description": "Similarity score (0-1)" }, "tags": { "type": "object", "description": "Tag values for this memory", "properties": { "tag_1": { "type": "string" }, "tag_2": { "type": "string" }, "tag_3": { "type": "string" }, "tag_4": { "type": "string" }, "tag_5": { "type": "string" }, "tag_6": { "type": "string" }, "tag_7": { "type": "string" }, "tag_8": { "type": "string" }, "tag_9": { "type": "string" }, "tag_10": { "type": "string" }, "tag_11": { "type": "string" }, "tag_12": { "type": "string" } } }, "metadata": { "type": "object", "description": "Additional metadata" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Memory service" }, "500": { "description": "Memory service error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Search query for semantic matching" }, "tag_1": { "type": "string", "description": "Filter by tag_1" }, "tag_2": { "type": "string", "description": "Filter by tag_2" }, "tag_3": { "type": "string", "description": "Filter by tag_3" }, "tag_4": { "type": "string", "description": "Filter by tag_4" }, "tag_5": { "type": "string", "description": "Filter by tag_5" }, "tag_6": { "type": "string", "description": "Filter by tag_6" }, "tag_7": { "type": "string", "description": "Filter by tag_7" }, "tag_8": { "type": "string", "description": "Filter by tag_8" }, "tag_9": { "type": "string", "description": "Filter by tag_9" }, "tag_10": { "type": "string", "description": "Filter by tag_10" }, "tag_11": { "type": "string", "description": "Filter by tag_11" }, "tag_12": { "type": "string", "description": "Filter by tag_12" }, "category": { "type": "string", "description": "Filter by category" }, "top_k": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100, "description": "Maximum number of results to return" } } } } } }, "x-permissions": [ "memory:read" ] } }, "/ocr/v1/{id}": { "get": { "tags": [ "OCR" ], "summary": "Get OCR job status", "description": "Retrieve the status and results of an OCR job. Returns job progress and metadata; full extracted text is included only when include_text=true.", "operationId": "getOcrJob", "responses": { "200": { "description": "OCR job status and results", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status", "created_at" ], "properties": { "id": { "type": "string", "description": "OCR job ID" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "Current job status" }, "error": { "type": "string", "nullable": true, "description": "Safe human-readable failure message; null when no failure is recorded." }, "error_code": { "type": "string", "nullable": true, "description": "Stable failure identifier, such as source_access_denied, invalid_pdf, inference_failed, chunks_failed, or result_upload_failed. Historic failures may be unclassified." }, "error_stage": { "type": "string", "nullable": true, "enum": [ "dispatch", "download", "document_validation", "chunking", "engine_init", "inference", "feature_processing", "result_write", "chunk_processing", "result_assembly", "result_upload" ], "description": "Operation that failed." }, "retryable": { "type": "boolean", "nullable": true, "description": "Whether retrying the same document may help. Unknown failures retain bounded retry behavior." }, "failed_chunks": { "type": "array", "nullable": true, "maxItems": 20, "description": "Bounded failure samples. Page ranges are one-based and inclusive; chunks_failed and chunk_count retain exact totals.", "items": { "type": "object", "properties": { "chunk_id": { "type": "string" }, "page_start": { "type": "integer", "minimum": 1 }, "page_end": { "type": "integer", "minimum": 1 }, "error": { "type": "string" }, "error_code": { "type": "string" }, "error_stage": { "type": "string" }, "retryable": { "type": "boolean" } } } }, "chunks_failed": { "type": "integer", "minimum": 0, "description": "Exact number of failed OCR chunks." }, "chunk_count": { "type": "integer", "minimum": 0, "description": "Total number of OCR chunks." }, "page_count": { "type": "integer", "description": "Number of pages processed" }, "text": { "type": "string", "description": "Extracted text content when completed and include_text=true" }, "metadata": { "type": "object", "description": "Additional processing metadata" }, "created_at": { "type": "string", "format": "date-time", "description": "Job creation timestamp" }, "completed_at": { "type": "string", "format": "date-time", "description": "Job completion timestamp" } } }, "example": { "id": "ocr_abc123", "status": "completed", "page_count": 15, "metadata": { "confidence": 0.95, "language": "en" }, "created_at": "2024-01-15T10:30:00Z", "completed_at": "2024-01-15T10:32:15Z" } } } }, "400": { "description": "Bad request - Invalid OCR ID format" }, "401": { "description": "Unauthorized - Invalid or missing API key" }, "404": { "description": "OCR job not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The OCR job ID returned from the create OCR endpoint" }, { "name": "include_text", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Include full OCR text in completed responses (default: false)" } ], "x-permissions": [ "vision_ocr" ] } }, "/ocr/v1/{id}/download/{type}": { "get": { "tags": [ "OCR" ], "summary": "Download OCR results", "description": "Download OCR processing results in various formats by redirecting to the OCR service download URL.", "operationId": "downloadOcrResults", "responses": { "200": { "description": "OCR result file download", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Type": { "description": "MIME type based on download type", "schema": { "type": "string" } }, "Content-Disposition": { "description": "Attachment with filename", "schema": { "type": "string" } }, "Content-Length": { "description": "File size in bytes", "schema": { "type": "string" } } } }, "302": { "description": "Redirect to the OCR service download URL", "headers": { "Location": { "description": "Short-lived URL for direct OCR result download", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Invalid OCR ID, type parameter, or unsupported download format" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "API key does not have access to OCR service" }, "404": { "description": "OCR job not found or results not available" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "OCR job ID returned from the initial OCR request" }, { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "text", "json", "pdf", "original" ] }, "description": "Format to download: `text` (plain text), `json` (structured data with coordinates), `pdf` (searchable PDF with text layer), `original` (original uploaded document)" } ], "x-permissions": [ "vision_ocr" ] } }, "/ocr/v1/health": { "get": { "tags": [ "OCR" ], "summary": "Health check", "description": "Unauthenticated health check for the OCR service.", "operationId": "getOCRHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "ocr" } } } } } } }, "/ocr/v1/process": { "post": { "tags": [ "OCR" ], "summary": "Process document with OCR", "description": "Submit a document for OCR processing to extract text, detect tables, forms, and other features. Supports PDFs, images, and scanned documents. Returns a job ID that can be used to track processing status.", "operationId": "processOcrDocument", "responses": { "201": { "description": "OCR job created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique job identifier" }, "status": { "type": "string", "description": "Current job status", "enum": [ "queued", "processing", "completed", "failed" ] }, "document_id": { "type": "string", "description": "Document identifier" }, "engine": { "type": "string", "description": "OCR engine used" }, "page_count": { "type": "integer", "description": "Number of pages detected" }, "created_at": { "type": "string", "format": "date-time", "description": "Job creation timestamp" }, "estimated_completion": { "type": "string", "format": "date-time", "description": "Estimated completion time" } } }, "example": { "id": "ocr_job_67890", "status": "queued", "document_id": "contract-2024-001", "engine": "doctr", "page_count": 15, "created_at": "2024-01-15T10:30:00Z", "estimated_completion": "2024-01-15T10:45:00Z" } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions for OCR service" }, "503": { "description": "OCR task dispatch is temporarily unavailable. Safe diagnostics are returned in data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 503 }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "error": { "type": "string", "example": "OCR task dispatch is temporarily unavailable." }, "error_code": { "type": "string", "example": "dispatch_failed" }, "error_stage": { "type": "string", "example": "dispatch" }, "retryable": { "type": "boolean", "example": true } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_url" ], "properties": { "document_url": { "type": "string", "description": "HTTP(S) URL of the document to process, or the s3:// path of a vault object in your organization", "example": "https://example.com/contract.pdf" }, "document_id": { "type": "string", "description": "Optional custom document identifier", "example": "contract-2024-001" }, "callback_url": { "type": "string", "description": "URL to receive completion webhook", "example": "https://your-app.com/webhooks/ocr-complete" }, "engine": { "type": "string", "description": "OCR engine to use", "enum": [ "doctr", "paddleocr" ], "default": "doctr", "example": "doctr" }, "features": { "type": "object", "description": "Additional processing options", "properties": { "embed": { "type": "object", "description": "Generate searchable PDF with text layer", "additionalProperties": true }, "tables": { "type": "object", "description": "Extract tables as structured data", "properties": { "format": { "type": "string", "enum": [ "csv", "json" ], "description": "Output format for extracted tables" } }, "additionalProperties": true }, "forms": { "type": "object", "description": "Detect and extract form fields", "additionalProperties": true } }, "example": { "embed": {}, "tables": { "format": "csv" } } }, "result_bucket": { "type": "string", "description": "S3 bucket to store results", "example": "my-ocr-results" }, "result_prefix": { "type": "string", "description": "S3 key prefix for results", "example": "ocr/2024/" } } } } } }, "x-permissions": [ "vision_ocr" ] } }, "/privilege/v1/detect": { "post": { "tags": [ "Privilege" ], "summary": "Detect privileged content", "description": "Analyzes text or vault documents for legal privilege review. Detects attorney-client privilege, work product doctrine, and common interest privilege.\n\nReturns structured review flags with confidence scores and policy-friendly rationale suitable for discovery workflows and privilege logs. This endpoint is an AI-assisted triage tool and does not replace attorney judgment.\n\n**Size Limit:** Maximum 200,000 characters (larger documents rejected).\n\n**Permissions:** Requires `chat` permission. When using `document_id`, also requires `vault` permission.\n\n**Note:** When analyzing vault documents, results are automatically stored in the document's `privilege_analysis` metadata field.", "operationId": "detectPrivilege", "responses": { "200": { "description": "Privilege analysis completed", "content": { "application/json": { "schema": { "type": "object", "required": [ "privileged", "confidence", "categories", "recommendation", "policy_rationale" ], "properties": { "privileged": { "type": "boolean", "description": "Whether any privilege was detected" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Overall confidence score (0-1)" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Privilege category" }, "detected": { "type": "boolean", "description": "Whether this privilege type was detected" }, "confidence": { "type": "number", "description": "Confidence for this category (0-1)" }, "rationale": { "type": "string", "description": "Explanation of detection result" }, "indicators": { "type": "array", "items": { "type": "string" }, "description": "Specific phrases or patterns found" } } } }, "recommendation": { "type": "string", "enum": [ "withhold", "redact", "produce", "review" ], "description": "Recommended action for discovery" }, "policy_rationale": { "type": "string", "description": "Policy-friendly explanation for privilege log" } } } } } }, "400": { "description": "Invalid request - missing content/document_id or content exceeds size limit" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to chat service" }, "404": { "description": "Vault or document not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Text content to analyze (required if document_id not provided)" }, "document_id": { "type": "string", "description": "Vault object ID to analyze (required if content not provided)" }, "vault_id": { "type": "string", "description": "Vault ID (required when using document_id)" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "attorney_client", "work_product", "common_interest" ] }, "description": "Privilege categories to check. Defaults to all: attorney_client, work_product, common_interest" }, "jurisdiction": { "type": "string", "enum": [ "US-Federal" ], "default": "US-Federal", "description": "Jurisdiction for privilege rules" }, "include_rationale": { "type": "boolean", "default": true, "description": "Include detailed rationale for each category" }, "model": { "type": "string", "default": "casemark/core-large", "description": "LLM model to use for analysis" } } } } } }, "x-permissions": [ "chat" ] } }, "/search/v1/answer": { "post": { "tags": [ "Search" ], "summary": "Generate AI-powered answers from web search", "description": "Generate comprehensive answers to questions using web search results. Supports two modes: native provider answers or custom LLM-powered answers using Case.dev's AI gateway. Perfect for legal research, fact-checking, and gathering supporting evidence for cases.", "operationId": "generateAnswer", "responses": { "200": { "description": "Answer generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "answer": { "type": "string", "description": "The generated answer with citations" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "publishedDate": { "type": "string" }, "text": { "type": "string" } } }, "description": "Sources used to generate the answer" }, "model": { "type": "string", "description": "Model used for answer generation" }, "searchType": { "type": "string", "description": "Type of search performed" } } } } } }, "400": { "description": "Invalid request - missing query or validation error" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Search service" } }, "requestBody": { "description": "Answer generation configuration", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The question or topic to research and answer" }, "useCustomLLM": { "type": "boolean", "description": "Use Case.dev LLM for answer generation instead of provider's native answer", "default": false }, "model": { "type": "string", "description": "LLM model to use when useCustomLLM is true", "default": "gpt-4o" }, "searchType": { "type": "string", "enum": [ "auto", "web", "news", "academic" ], "description": "Type of search to perform", "default": "auto" }, "numResults": { "type": "integer", "description": "Number of search results to consider", "minimum": 1, "maximum": 50, "default": 10 }, "includeDomains": { "type": "array", "items": { "type": "string" }, "description": "Only search within these domains" }, "excludeDomains": { "type": "array", "items": { "type": "string" }, "description": "Exclude these domains from search" }, "temperature": { "type": "number", "description": "LLM temperature for answer generation", "minimum": 0, "maximum": 2, "default": 0.3 }, "maxTokens": { "type": "integer", "description": "Maximum tokens for LLM response", "default": 2048 }, "text": { "type": "boolean", "description": "Include text content in response", "default": true }, "stream": { "type": "boolean", "description": "Stream the response (only for native provider answers)", "default": false } } } } } }, "x-permissions": [ "search" ] } }, "/search/v1/contents": { "post": { "tags": [ "Search" ], "summary": "Extract content from URLs", "description": "Scrapes and extracts text content from web pages, PDFs, and documents. Useful for legal research, evidence collection, and document analysis. Supports live crawling, subpage extraction, and content summarization.", "operationId": "getContentsFromUrls", "responses": { "200": { "description": "Content successfully extracted from URLs", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Source URL" }, "title": { "type": "string", "description": "Page title" }, "text": { "type": "string", "description": "Extracted text content" }, "summary": { "type": "string", "description": "Content summary if requested" }, "highlights": { "type": "array", "items": { "type": "string" }, "description": "Content highlights if requested" }, "metadata": { "type": "object", "description": "Additional metadata about the content" } } } } } } } } }, "400": { "description": "Invalid request - missing or invalid URLs array" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Search service" }, "500": { "description": "Internal server error during content extraction" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "urls" ], "properties": { "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "Array of URLs to scrape and extract content from" }, "text": { "type": "boolean", "description": "Whether to extract text content", "default": true }, "highlights": { "type": "boolean", "description": "Whether to include content highlights", "default": false }, "summary": { "type": "boolean", "description": "Whether to generate content summaries", "default": false }, "livecrawl": { "type": "boolean", "description": "Whether to perform live crawling for dynamic content", "default": false }, "livecrawlTimeout": { "type": "integer", "description": "Timeout in seconds for live crawling", "default": 30 }, "subpages": { "type": "boolean", "description": "Whether to extract content from linked subpages", "default": false }, "subpageTarget": { "type": "integer", "description": "Maximum number of subpages to crawl", "default": 5 }, "extras": { "type": "object", "description": "Additional extraction options" }, "context": { "type": "string", "description": "Context to guide content extraction and summarization" } } } } } }, "x-permissions": [ "search" ] } }, "/search/v1/health": { "get": { "tags": [ "Search" ], "summary": "Health check", "description": "Unauthenticated health check for the Search service.", "operationId": "getSearchHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "search" } } } } } } }, "/search/v1/search": { "post": { "tags": [ "Search" ], "summary": "Perform intelligent web search", "description": "Executes intelligent web search queries with advanced filtering and customization options. Ideal for legal research, case law discovery, and gathering supporting documentation for litigation or compliance matters.", "operationId": "search", "responses": { "200": { "description": "Search completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of search results", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the search result" }, "url": { "type": "string", "description": "URL of the search result" }, "snippet": { "type": "string", "description": "Brief excerpt from the content" }, "publishedDate": { "type": "string", "format": "date-time", "description": "Publication date of the content" }, "domain": { "type": "string", "description": "Domain of the source" } } } }, "query": { "type": "string", "description": "Original search query" }, "totalResults": { "type": "integer", "description": "Total number of results found" } } } } } }, "400": { "description": "Bad request - invalid query or parameters" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - insufficient permissions for Search service" } }, "requestBody": { "description": "Search query and filtering options", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Primary search query" }, "additionalQueries": { "type": "array", "items": { "type": "string" }, "description": "Additional related search queries to enhance results" }, "type": { "type": "string", "enum": [ "auto", "search", "news" ], "default": "auto", "description": "Type of search to perform" }, "category": { "type": "string", "description": "Category filter for search results" }, "userLocation": { "type": "string", "description": "Geographic location for localized results" }, "numResults": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100, "description": "Number of search results to return" }, "includeDomains": { "type": "array", "items": { "type": "string" }, "description": "Domains to include in search results" }, "excludeDomains": { "type": "array", "items": { "type": "string" }, "description": "Domains to exclude from search results" }, "startCrawlDate": { "type": "string", "format": "date", "description": "Start date for crawl date filtering" }, "endCrawlDate": { "type": "string", "format": "date", "description": "End date for crawl date filtering" }, "startPublishedDate": { "type": "string", "format": "date", "description": "Start date for published date filtering" }, "endPublishedDate": { "type": "string", "format": "date", "description": "End date for published date filtering" }, "includeText": { "type": "boolean", "description": "Whether to include full text content in results" }, "contents": { "type": "string", "description": "Specific content type to search for" } } } } } }, "x-permissions": [ "search" ] } }, "/search/v1/similar": { "post": { "tags": [ "Search" ], "summary": "Find similar content", "description": "Find web pages and documents similar to a given URL. Useful for legal research to discover related case law, statutes, or legal commentary that shares similar themes or content structure.", "operationId": "findSimilarContent", "responses": { "200": { "description": "Successfully found similar content", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "snippet": { "type": "string" }, "similarityScore": { "type": "number" }, "publishedDate": { "type": "string" }, "domain": { "type": "string" }, "text": { "type": "string" } } } }, "totalResults": { "type": "integer" }, "processingTime": { "type": "number" } } } } } }, "400": { "description": "Invalid request parameters or missing URL" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to Search service" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to find similar content for" }, "numResults": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Number of similar results to return" }, "includeDomains": { "type": "array", "items": { "type": "string" }, "description": "Only search within these domains" }, "excludeDomains": { "type": "array", "items": { "type": "string" }, "description": "Exclude results from these domains" }, "startCrawlDate": { "type": "string", "format": "date", "description": "Only include pages crawled after this date" }, "endCrawlDate": { "type": "string", "format": "date", "description": "Only include pages crawled before this date" }, "startPublishedDate": { "type": "string", "format": "date", "description": "Only include pages published after this date" }, "endPublishedDate": { "type": "string", "format": "date", "description": "Only include pages published before this date" }, "includeText": { "type": "boolean", "description": "Whether to include extracted text content in results" }, "contents": { "type": "string", "description": "Additional content to consider for similarity matching" } } } } } }, "x-permissions": [ "search" ] } }, "/services": { "get": { "tags": [ "System" ], "summary": "List documented services", "description": "Returns the public Case.dev services catalog derived from docs.case.dev/services. This endpoint is unauthenticated and intended for discovery surfaces such as the case.dev homepage.", "operationId": "listServices", "responses": { "200": { "description": "Services catalog retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "href": { "type": "string" }, "order": { "type": "integer" } }, "required": [ "id", "name", "description", "icon", "href", "order" ] } } }, "required": [ "services" ] } } } } } } }, "/skills": { "post": { "tags": [ "Skills" ], "summary": "Create custom skill", "description": "Create an org-scoped custom skill. The skill will be searchable via /skills/resolve alongside curated skills.", "operationId": "createCustomSkill", "responses": { "201": { "description": "Skill created", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "content": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "bundle": { "type": "object", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "409": { "description": "Slug already exists in this org" } }, "requestBody": { "description": "Skill definition", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "content" ], "properties": { "name": { "type": "string", "description": "Skill name", "minLength": 1, "maxLength": 256 }, "slug": { "type": "string", "description": "URL-safe slug. Auto-generated from name if omitted.", "maxLength": 128 }, "summary": { "type": "string", "description": "Brief description (1-2 sentences)", "maxLength": 1024 }, "content": { "type": "string", "description": "Full skill content in markdown", "minLength": 1, "maxLength": 65536 }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for categorization and search boosting" }, "metadata": { "type": "object", "description": "Arbitrary metadata (author, license, etc.)" }, "files": { "type": "array", "description": "Optional bundled companion files installed alongside the skill as / in sandbox skill directories. The complete file set may contain at most 12 MiB of decoded content.", "maxItems": 100, "items": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "description": "Relative path inside the skill directory. SKILL.md is reserved for the root skill content.", "maxLength": 512 }, "content": { "type": "string", "maxLength": 349528, "description": "UTF-8 text when encoding is utf8 (max 65,536 characters), or canonical base64 when encoding is base64 (max 262,144 decoded bytes)." }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "default": "utf8", "description": "How content is encoded. Omit for UTF-8 text files." }, "name": { "type": "string", "maxLength": 256 }, "summary": { "type": "string", "maxLength": 1024 }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "contentType": { "type": "string", "maxLength": 100 } } } } } } } } }, "x-permissions": [ "skills" ] } }, "/skills/{slug}": { "get": { "tags": [ "Skills" ], "summary": "Read skill", "description": "Read the full content of a legal skill by its slug. Returns markdown content, tags, and metadata. Slugs of merged skills are permanent aliases: they return the surviving skill with `redirected_from` set to the requested slug instead of an error.", "operationId": "readSkill", "responses": { "200": { "description": "Skill details", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique skill identifier" }, "name": { "type": "string", "description": "Skill name" }, "summary": { "type": "string", "description": "Brief skill description" }, "content": { "type": "string", "description": "Full skill content in markdown" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Skill tags" }, "version": { "type": "string", "description": "Skill version" }, "author_name": { "type": "string", "description": "Skill author" }, "license": { "type": "string", "description": "Skill license" }, "metadata": { "type": "object", "description": "Custom metadata (custom skills only)" }, "bundle": { "type": "object", "nullable": true, "description": "Skill bundle metadata for root skills and companion file rows", "oneOf": [ { "type": "object", "required": [ "role", "files" ], "properties": { "role": { "type": "string", "enum": [ "root" ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "slug", "path" ], "properties": { "slug": { "type": "string" }, "path": { "type": "string" }, "name": { "type": "string", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "description": "Encoding used by content when this companion slug is read." } } } } } }, { "type": "object", "required": [ "role", "root_slug", "path" ], "properties": { "role": { "type": "string", "enum": [ "file" ] }, "root_slug": { "type": "string" }, "path": { "type": "string" }, "content_type": { "type": "string", "nullable": true }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "description": "Encoding of the returned content field." } } } ] }, "source": { "type": "string", "enum": [ "curated", "custom" ], "description": "Skill source (authenticated requests only)" }, "redirected_from": { "type": "string", "description": "Present only when the requested slug is a permanent alias of a merged skill. Holds the slug that was requested; every other field (including slug) describes the target skill. Omitted for non-alias reads." } } } } } }, "400": { "description": "Missing slug parameter" }, "404": { "description": "Skill not found" }, "429": { "description": "Rate limit exceeded (anonymous users)" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique skill slug identifier" } ], "x-permissions": [ "skills" ] }, "put": { "tags": [ "Skills" ], "summary": "Update custom skill", "description": "Update an org-scoped custom skill by slug. Only provided fields are updated. Version is auto-incremented.", "operationId": "updateCustomSkill", "responses": { "200": { "description": "Skill updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "content": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "bundle": { "type": "object", "nullable": true }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Skill not found in this org" }, "409": { "description": "Slug or expected version conflict" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill slug to update" } ], "requestBody": { "description": "Fields to update", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 256 }, "slug": { "type": "string", "description": "New slug (renames the skill)", "maxLength": 128 }, "summary": { "type": "string", "maxLength": 1024, "nullable": true }, "content": { "type": "string" }, "expectedVersion": { "type": "integer", "minimum": 0, "description": "Reject with 409 if the skill changed since this version was read." }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "files": { "type": "array", "nullable": true, "description": "Optional replacement companion file tree, limited to 12 MiB of decoded content. Omit to leave existing bundled files unchanged; send [] to remove bundled files.", "maxItems": 100, "items": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "maxLength": 512 }, "content": { "type": "string", "maxLength": 349528, "description": "UTF-8 text when encoding is utf8 (max 65,536 characters), or canonical base64 when encoding is base64 (max 262,144 decoded bytes)." }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "default": "utf8", "description": "How content is encoded. Omit for UTF-8 text files." }, "name": { "type": "string", "maxLength": 256 }, "summary": { "type": "string", "maxLength": 1024 }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "contentType": { "type": "string", "maxLength": 100 } } } } } } } } }, "x-permissions": [ "skills" ] }, "delete": { "tags": [ "Skills" ], "summary": "Delete custom skill", "description": "Soft-delete an org-scoped custom skill by slug. The skill will no longer appear in search results.", "operationId": "deleteCustomSkill", "responses": { "200": { "description": "Skill deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Skill not found in this org" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill slug to delete" } ], "x-permissions": [ "skills" ] } }, "/skills/{slug}/export": { "get": { "tags": [ "Skills" ], "summary": "Export skill tree", "description": "Export a skill as an installable filesystem tree for sandbox runtimes. Authenticated org-scoped custom skills are resolved before curated skills. Slugs of merged skills are permanent aliases: they export the surviving skill (slug, root and files describe the target) with `redirected_from` set to the requested slug.", "operationId": "exportSkillTree", "responses": { "200": { "description": "Installable skill tree", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "target": { "type": "string" }, "root": { "type": "string" }, "source": { "type": "string", "enum": [ "custom", "curated" ] }, "redirected_from": { "type": "string", "description": "Present only when the requested slug is a permanent alias of a merged skill. Holds the requested slug; slug, root and files describe the target skill." }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "content_type": { "type": "string" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ], "description": "Encoding of content. Binary files use canonical base64." }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer" } } } } } } } } }, "400": { "description": "Missing slug or unsupported target" }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Skill not found" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Skill slug to export" }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string", "default": "agents" }, "description": "Agent runtime skill directory convention to export for. Most callers should omit this and pass skillSlugs when creating a runtime." } ], "x-permissions": [ "skills" ] } }, "/skills/catalog": { "get": { "tags": [ "Skills" ], "summary": "Browse available skills", "description": "Browse public and organization skills using one authenticated catalog. Returns metadata only; skill content is loaded separately.", "operationId": "listSkillCatalog", "responses": { "200": { "description": "A page of skill metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "integer", "nullable": true }, "skills": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "custom", "curated" ] } } } } } } } } }, "400": { "description": "Invalid pagination or source filter" }, "401": { "description": "Authentication required" }, "403": { "description": "Skills read permission required" } }, "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Optional text search" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Optional tag filter" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "custom", "curated" ] }, "description": "Optional source filter, applied after organization overrides and before pagination. Omit to browse both sources." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of results to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum results to return" } ], "x-permissions": [ "skills" ] } }, "/skills/custom": { "get": { "tags": [ "Skills" ], "summary": "List custom skills", "description": "List all custom skills for the authenticated organization. Supports cursor-based pagination.", "operationId": "listCustomSkills", "responses": { "200": { "description": "List of custom skills", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Insufficient permissions" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of results (1-100)" }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination (skill ID from previous page)" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "Filter by tag" } ], "x-permissions": [ "skills" ] } }, "/skills/resolve": { "get": { "tags": [ "Skills" ], "summary": "Search skills", "description": "Search the Legal Skills Store using hybrid search (text + tag + semantic). Returns ranked results with relevance scores.", "operationId": "resolveSkill", "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique skill identifier" }, "name": { "type": "string", "description": "Skill name" }, "summary": { "type": "string", "description": "Brief skill description" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Skill tags" }, "score": { "type": "number", "description": "Relevance score" }, "source": { "type": "string", "enum": [ "curated", "custom" ], "description": "Whether the skill is curated or org-custom" } } } }, "methods_used": { "type": "array", "items": { "type": "string" }, "description": "Search methods used (text, tag, semantic)" } } } } } }, "400": { "description": "Missing or invalid query parameter" }, "429": { "description": "Rate limit exceeded (anonymous users)" } }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query string" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "description": "Maximum number of results to return (1-20)" } ], "x-permissions": [ "skills" ] } }, "/system/health": { "get": { "tags": [ "System" ], "summary": "Health check", "description": "Unauthenticated health check for the System service.", "operationId": "getSystemHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "system" } } } } } } } } }, "/translate/v1/detect": { "post": { "tags": [ "Translation" ], "summary": "Detect language", "description": "Detect the language of text. Returns the most likely language code and confidence score. Supports batch detection for multiple texts.", "operationId": "detectLanguage", "responses": { "200": { "description": "Language detection successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "detections": { "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "Detected language code (ISO 639-1)" }, "confidence": { "type": "number", "description": "Confidence score (0-1)" }, "isReliable": { "type": "boolean", "description": "Whether the detection is reliable" } } } } } } } } } } } }, "400": { "description": "Invalid request - missing text", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "q (text) is required" } } } } } }, "401": { "description": "Authentication failed - invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid API key" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "AUTH_INVALID" } } } } } } } }, "403": { "description": "Permission denied - API key lacks translation access", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 403 }, "message": { "type": "string", "example": "API key does not have access to translation service" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "PERMISSION_DENIED" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Text to detect language for. Can be a single string or an array for batch detection." } } } } } }, "x-permissions": [ "translation" ] } }, "/translate/v1/document": { "post": { "tags": [ "Translation" ], "summary": "Translate a document", "description": "Translate one TXT, DOCX, or searchable PDF document. DOCX and PDF translations preserve the source document format and retain as much layout and formatting as possible.", "operationId": "translateDocument", "responses": { "200": { "description": "Translated document in the source file format", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Type": { "description": "MIME type of the translated document", "schema": { "type": "string" } }, "Content-Disposition": { "description": "Attachment with the translated filename", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request or unsupported file type" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have translation access" }, "413": { "description": "File exceeds the 20MB limit" } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "target" ], "properties": { "file": { "type": "string", "format": "binary", "description": "TXT, DOCX, or searchable PDF document (max 20MB)" }, "target": { "type": "string", "description": "Target BCP-47 language code", "example": "es" }, "source": { "type": "string", "description": "Optional source BCP-47 language code. Auto-detected when omitted.", "example": "en" } } } } } }, "x-permissions": [ "translation" ] } }, "/translate/v1/health": { "get": { "tags": [ "Translation" ], "summary": "Health check", "description": "Unauthenticated health check for the Translation service.", "operationId": "getTranslationHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "translation" } } } } } } }, "/translate/v1/languages": { "get": { "tags": [ "Translation" ], "summary": "List supported languages", "description": "Get the list of languages supported for translation. Optionally specify a target language to get translated language names.", "operationId": "getSupportedLanguages", "responses": { "200": { "description": "List of supported languages", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "languages": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string", "description": "Language code (ISO 639-1)" }, "name": { "type": "string", "description": "Language name (if target specified)" } } } } } } } } } } }, "401": { "description": "Authentication failed - invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid API key" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "AUTH_INVALID" } } } } } } } }, "403": { "description": "Permission denied - API key lacks translation access", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 403 }, "message": { "type": "string", "example": "API key does not have access to translation service" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "PERMISSION_DENIED" } } } } } } } } }, "parameters": [ { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Target language code for translating language names (e.g., 'es' for Spanish names)" }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "nmt", "base" ] }, "description": "Translation model to check language support for" } ], "x-permissions": [ "translation" ] } }, "/translate/v1/translate": { "post": { "tags": [ "Translation" ], "summary": "Translate text", "description": "Translate text between languages using Google Cloud Translation API. Supports 100+ languages, automatic language detection, HTML preservation, and batch translation.", "operationId": "translateText", "responses": { "200": { "description": "Translation successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "translations": { "type": "array", "items": { "type": "object", "properties": { "translatedText": { "type": "string", "description": "Translated text" }, "detectedSourceLanguage": { "type": "string", "description": "Detected source language (if source not specified)" }, "model": { "type": "string", "description": "Model used for translation" } } } } } } } } } } }, "400": { "description": "Invalid request - missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "q (text) and target language are required" } } } } } }, "401": { "description": "Authentication failed - invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid API key" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "AUTH_INVALID" } } } } } } } }, "403": { "description": "Permission denied - API key lacks translation access", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 403 }, "message": { "type": "string", "example": "API key does not have access to translation service" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "PERMISSION_DENIED" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q", "target" ], "properties": { "q": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Text to translate. Can be a single string or an array for batch translation." }, "target": { "type": "string", "description": "Target language code (ISO 639-1)", "example": "es" }, "source": { "type": "string", "description": "Source language code (ISO 639-1). If not specified, language is auto-detected.", "example": "en" }, "format": { "type": "string", "enum": [ "text", "html" ], "default": "text", "description": "Format of the source text. Use 'html' to preserve HTML tags." }, "model": { "type": "string", "enum": [ "nmt", "base" ], "default": "nmt", "description": "Translation model. 'nmt' (Neural Machine Translation) is recommended for quality." } } } } } }, "x-permissions": [ "translation" ] } }, "/usage/v1": { "get": { "tags": [ "Usage" ], "summary": "Get usage snapshot", "description": "Returns customer-facing usage metrics and costs for the requested period. Supports summary totals and daily buckets for timestamped usage sources. Vault storage is intentionally omitted from totals because it is not yet periodized for arbitrary windows.", "operationId": "getUsageSnapshot", "responses": { "200": { "description": "Usage snapshot retrieved successfully" }, "400": { "description": "Invalid query parameters" }, "401": { "description": "Invalid API key or session" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Linc session not found" }, "409": { "description": "Linc session usage is unavailable" } }, "parameters": [ { "name": "periodStart", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Period start date. Defaults to the start of the current calendar month." }, { "name": "periodEnd", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Period end date. Defaults to now." }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "summary", "daily" ], "default": "summary" }, "description": "Whether to return period totals only or include daily buckets." }, { "name": "lincSessionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Restrict usage to a native Linc session. The session must belong to the authenticated organization." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "lincSessionId" ] }, "description": "Optionally include usage groups keyed by native Linc session id. Only Linc-session-attributable usage is grouped." } ], "x-permissions": [ "billing:read" ] } }, "/usage/v1/subscriptions": { "get": { "tags": [ "Usage" ], "summary": "List usage webhook subscriptions", "description": "Lists webhook subscriptions configured for usage and billing events.", "operationId": "listUsageEventSubscriptions", "responses": { "200": { "description": "Subscriptions retrieved successfully" }, "401": { "description": "Invalid API key or session" }, "403": { "description": "Insufficient permissions" } }, "x-permissions": [ "billing:read" ] }, "post": { "tags": [ "Usage" ], "summary": "Create usage webhook subscription", "description": "Creates a webhook subscription for usage, balance, and billing events.", "operationId": "createUsageEventSubscription", "responses": { "201": { "description": "Usage webhook subscription created successfully" }, "400": { "description": "Invalid request payload" }, "401": { "description": "Invalid API key or session" }, "403": { "description": "Insufficient permissions" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "callbackUrl" ], "properties": { "callbackUrl": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "signingSecret": { "type": "string" } } } } } }, "x-permissions": [ "billing:write" ] } }, "/usage/v1/subscriptions/{subscriptionId}": { "patch": { "tags": [ "Usage" ], "summary": "Update usage webhook subscription", "description": "Updates callback URL, event filters, active state, or signing secret.", "operationId": "updateUsageEventSubscription", "responses": { "200": { "description": "Subscription updated successfully" }, "400": { "description": "Invalid request payload" }, "401": { "description": "Invalid API key or session" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Subscription not found" } }, "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "callbackUrl": { "type": "string", "format": "uri" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "signingSecret": { "type": "string" }, "clearSigningSecret": { "type": "boolean" } } } } } }, "x-permissions": [ "billing:write" ] }, "delete": { "tags": [ "Usage" ], "summary": "Delete usage webhook subscription", "description": "Deactivates a usage webhook subscription.", "operationId": "deleteUsageEventSubscription", "responses": { "200": { "description": "Subscription deleted" }, "401": { "description": "Invalid API key or session" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Subscription not found" } }, "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "billing:write" ] } }, "/usage/v1/subscriptions/{subscriptionId}/test": { "post": { "tags": [ "Usage" ], "summary": "Send test usage webhook event", "description": "Delivers a test event to a single usage webhook subscription using the same payload shape and signing behavior as production delivery.", "operationId": "testUsageEventSubscription", "responses": { "200": { "description": "Test event attempted" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid API key or session" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Subscription not found" } }, "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string" }, "payload": { "type": "object", "additionalProperties": true } } } } } }, "x-permissions": [ "billing:write" ] } }, "/vault": { "get": { "tags": [ "Vaults" ], "summary": "List all vaults", "description": "List all vaults for the authenticated organization. Returns vault metadata including name, description, storage configuration, and usage statistics. Pagination is opt-in: pass `limit` (1-200) to receive a bounded page, then replay `pagination.next_cursor` as `?cursor=` while `pagination.has_more` is true. A request with neither `limit` nor `cursor` still returns every vault, and `pagination.limit` is null. That default will become a bounded page in a future release — paginate now to avoid the change.", "operationId": "listVaults", "responses": { "200": { "description": "Vaults retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "vaults": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Vault identifier" }, "name": { "type": "string", "description": "Vault name" }, "description": { "type": "string", "description": "Vault description" }, "totalObjects": { "type": "integer", "description": "Number of stored documents" }, "totalBytes": { "type": "integer", "description": "Total storage size in bytes" }, "createdAt": { "type": "string", "format": "date-time", "description": "Vault creation timestamp" } } } }, "total": { "type": "integer", "description": "Number of vaults in this response" }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "nullable": true }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } }, "totals": { "type": "object", "description": "Present only with `include_totals=true`. Covers every vault matching the filters, across all pages.", "properties": { "vaults": { "type": "integer" }, "totalObjects": { "type": "integer" }, "totalBytes": { "type": "integer" } } } } }, "example": { "vaults": [ { "id": "vault_abc123", "name": "Contract Repository", "description": "Secure storage for client contracts", "totalObjects": 1247, "totalBytes": 2847362048, "createdAt": "2024-01-01T00:00:00Z" } ], "total": 1 } } } }, "400": { "description": "Invalid cursor or limit" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Vaults per page (1-200). Omit to receive every vault. Supplying a cursor without a limit uses 50." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque continuation cursor from `pagination.next_cursor` of the previous page. Must be replayed with the same API key scope and `query` that produced it." }, { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Case-insensitive substring match on the vault name." }, { "name": "include_totals", "in": "query", "schema": { "type": "boolean" }, "description": "When `true`, adds `totals` covering every vault matching the filters, not just this page. Scans all objects in those vaults, so request it once per filter change rather than on every page." } ], "x-permissions": [ "vault" ] }, "post": { "tags": [ "Vaults" ], "summary": "Create a new vault", "description": "Creates a new secure vault with dedicated S3 storage and vector search capabilities. Each vault provides isolated document storage with semantic search and OCR processing for legal document analysis and discovery.", "operationId": "createVault", "responses": { "201": { "description": "Vault created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique vault identifier" }, "name": { "type": "string", "description": "Vault display name" }, "description": { "type": "string", "description": "Vault description" }, "filesBucket": { "type": "string", "description": "S3 bucket name for document storage" }, "vectorBucket": { "type": "string", "nullable": true, "description": "S3 bucket name for vector embeddings. Null for storage-only vaults." }, "indexName": { "type": "string", "nullable": true, "description": "Vector search index name. Null for storage-only vaults." }, "enableIndexing": { "type": "boolean", "description": "Whether vector indexing is enabled for this vault" }, "region": { "type": "string", "description": "AWS region for storage" }, "embeddingProfile": { "type": "object", "nullable": true, "description": "The resolved embedding profile for this vault. Null for storage-only vaults.", "properties": { "model": { "type": "string", "description": "Embedding model catalog key" }, "provider": { "type": "string", "description": "Embedding provider" }, "dimensions": { "type": "integer", "description": "Vector dimension used by this vault" } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Vault creation timestamp" } } }, "example": { "id": "vault_2NqPkJ8xK9LmN3pQ", "name": "Contract Review Archive", "description": "Repository for all client contract reviews and analysis", "filesBucket": "case-vault-acme-legal-vault_2NqPkJ8xK9LmN3pQ", "vectorBucket": "case-vault-acme-legal-vault_2NqPkJ8xK9LmN3pQ-vectors", "indexName": "embeddings", "enableIndexing": true, "region": "us-east-1", "createdAt": "2024-01-15T10:30:00Z" } } } }, "400": { "description": "Invalid request parameters - missing vault name" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Organization not found" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name for the vault", "example": "Contract Review Archive" }, "description": { "type": "string", "description": "Optional description of the vault's purpose", "example": "Repository for all client contract reviews and analysis" }, "enableIndexing": { "type": "boolean", "description": "Enable vector indexing and search capabilities. Set to false for storage-only vaults.", "default": true, "example": true }, "metadata": { "type": "object", "description": "Optional metadata to attach to the vault (e.g., { containsPHI: true } for HIPAA compliance tracking)", "example": { "containsPHI": true, "hipaaCompliant": true } }, "groupId": { "type": "string", "description": "Assign the vault to a vault group for access control. Required when using a group-scoped API key.", "example": "grp_abc123" }, "embeddingModel": { "type": "string", "description": "Optional embedding model for this vault. Defaults to casemark/embed-v1. Determines the S3 Vectors index dimension and which model is used at both ingest and search time. The vault is locked to this model after creation — use a re-embed flow to change later. Ignored when enableIndexing is false. Note: `casemark/llama-nemotron-embed-vl-1b-v2` is a deprecated alias for `casemark/embed-v1` (retained for SDK backward compatibility); new integrations should use `casemark/embed-v1` directly.", "enum": [ "openai/text-embedding-3-small", "openai/text-embedding-3-large", "voyage/voyage-3.5", "voyage/voyage-law-2", "cohere/embed-v4.0", "google/gemini-embedding-2", "casemark/embed-v1", "casemark/llama-nemotron-embed-vl-1b-v2" ], "default": "casemark/embed-v1", "example": "casemark/embed-v1" } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}": { "get": { "tags": [ "Vaults" ], "summary": "Get vault information", "description": "Retrieve detailed information about a specific vault, including storage configuration, chunking strategy, and usage statistics. Returns vault metadata, bucket information, and vector storage details.", "operationId": "getVault", "responses": { "200": { "description": "Vault information retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "filesBucket", "region", "createdAt" ], "properties": { "id": { "type": "string", "description": "Vault identifier" }, "name": { "type": "string", "description": "Vault name" }, "description": { "type": "string", "description": "Vault description" }, "filesBucket": { "type": "string", "description": "S3 bucket for document storage" }, "vectorBucket": { "type": "string", "nullable": true, "description": "S3 bucket for vector embeddings" }, "indexName": { "type": "string", "description": "Search index name" }, "region": { "type": "string", "description": "AWS region" }, "kmsKeyId": { "type": "string", "description": "KMS key for encryption" }, "chunkStrategy": { "type": "object", "description": "Document chunking strategy configuration", "properties": { "method": { "type": "string", "description": "Chunking method (e.g., 'semantic', 'fixed')" }, "overlap": { "type": "integer", "description": "Number of overlapping tokens between chunks" }, "chunkSize": { "type": "integer", "description": "Target size for each chunk in tokens" }, "minChunkSize": { "type": "integer", "description": "Minimum chunk size in tokens" } } }, "totalObjects": { "type": "integer", "description": "Number of stored documents" }, "totalBytes": { "type": "integer", "description": "Total storage size in bytes" }, "totalVectors": { "type": "integer", "description": "Number of vector embeddings" }, "metadata": { "type": "object", "description": "Additional vault metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Vault creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "example": { "id": "vault_abc123", "name": "Contract Repository", "description": "Secure storage for client contracts and legal documents", "filesBucket": "case-vault-files-abc123", "vectorBucket": "case-vault-vectors-abc123", "indexName": "contracts-index", "region": "us-east-1", "kmsKeyId": "arn:aws:kms:us-east-1:123456789:key/12345678-1234-1234-1234-123456789012", "chunkStrategy": { "method": "semantic", "overlap": 50, "chunkSize": 512, "minChunkSize": 100 }, "totalObjects": 1247, "totalBytes": 2847362048, "totalVectors": 45623, "metadata": { "vectorBucket": "case-vault-vectors-abc123", "lastIndexed": "2024-01-15T10:30:00Z" }, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "description": "Invalid vault ID provided" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the vault", "schema": { "type": "string" }, "example": "vault_abc123" } ], "x-permissions": [ "vault" ] }, "patch": { "tags": [ "Vaults" ], "summary": "Update vault settings", "description": "Update vault settings including name, description, and group membership.", "operationId": "updateVault", "responses": { "200": { "description": "Vault updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Vault identifier" }, "name": { "type": "string", "description": "Vault name" }, "description": { "type": "string", "nullable": true, "description": "Vault description" }, "filesBucket": { "type": "string", "description": "S3 bucket for document storage" }, "vectorBucket": { "type": "string", "nullable": true, "description": "S3 bucket for vector embeddings" }, "indexName": { "type": "string", "description": "Search index name" }, "region": { "type": "string", "description": "AWS region" }, "kmsKeyId": { "type": "string", "description": "KMS key for encryption" }, "chunkStrategy": { "type": "object", "description": "Document chunking strategy configuration" }, "totalObjects": { "type": "integer", "description": "Number of stored documents" }, "totalBytes": { "type": "integer", "description": "Total storage size in bytes" }, "totalVectors": { "type": "integer", "description": "Number of vector embeddings" }, "metadata": { "type": "object", "description": "Additional vault metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Vault creation timestamp" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "example": { "id": "vault_abc123", "name": "Updated Contract Repository", "description": "Updated description", "filesBucket": "case-vault-files-abc123", "vectorBucket": "case-vault-vectors-abc123", "indexName": "contracts-index", "region": "us-east-1", "kmsKeyId": "arn:aws:kms:us-east-1:123456789:key/12345678-1234-1234-1234-123456789012", "chunkStrategy": { "method": "semantic", "overlap": 50, "chunkSize": 512, "minChunkSize": 100 }, "totalObjects": 1247, "totalBytes": 2847362048, "totalVectors": 45623, "metadata": {}, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "description": "Invalid request - no fields to update or invalid field values" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the vault" }, "description": { "type": "string", "nullable": true, "description": "New description for the vault. Set to null to remove." }, "groupId": { "type": "string", "nullable": true, "description": "Move the vault to a different group, or set to null to remove from its current group." } } }, "example": { "name": "Updated Vault Name" } } } }, "x-permissions": [ "vault" ] }, "delete": { "tags": [ "Vaults" ], "summary": "Delete vault", "description": "Permanently deletes a vault and all its contents including documents, vectors, graph data, and S3 buckets. This operation cannot be undone. For large vaults, use the async=true query parameter to queue deletion in the background.", "operationId": "deleteVault", "responses": { "200": { "description": "Vault deleted successfully (or deletion queued if async)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "description": "Either 'deleted' or 'deletion_queued'" }, "deletedVault": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "objectsDeleted": { "type": "integer" }, "vectorsDeleted": { "type": "integer" }, "bytesFreed": { "type": "integer" } } } } }, "example": { "success": true, "status": "deleted", "deletedVault": { "id": "vault_abc123", "name": "Contract Repository", "objectsDeleted": 150, "vectorsDeleted": 4200, "bytesFreed": 2847362048 } } } } }, "202": { "description": "Deletion queued (async mode for large vaults)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" }, "vaultId": { "type": "string" }, "workflowId": { "type": "string", "description": "Workflow run ID for tracking deletion progress" }, "estimatedObjects": { "type": "integer" }, "message": { "type": "string" } } } } } }, "400": { "description": "Missing vault ID" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID to delete" }, { "name": "async", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "If true and vault has many objects, queue deletion in background and return immediately" } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/events/subscriptions": { "get": { "tags": [ "Vault Events" ], "summary": "List vault webhook subscriptions", "description": "Lists webhook subscriptions configured for a vault.", "operationId": "listVaultEventSubscriptions", "responses": { "200": { "description": "Subscriptions retrieved successfully" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "x-permissions": [ "vault:read" ] }, "post": { "tags": [ "Vault Events" ], "summary": "Create vault webhook subscription", "description": "Creates a webhook subscription for vault lifecycle events. Optional object filters can limit notifications to specific vault objects.", "operationId": "createVaultEventSubscription", "responses": { "201": { "description": "Vault webhook subscription created successfully" }, "400": { "description": "Webhook payload is invalid or references unknown vault objects" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have write access to vault service" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Reusing a key for this Vault updates and returns the same webhook subscription." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "callbackUrl" ], "properties": { "callbackUrl": { "type": "string", "format": "uri", "description": "Webhook endpoint URL that will receive vault event deliveries" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Vault event types to deliver. Omit to receive the default supported set." }, "objectIds": { "type": "array", "items": { "type": "string" }, "description": "Vault object IDs to limit notifications to. Omit to receive events for all objects in the vault." }, "signingSecret": { "type": "string", "description": "Optional secret used to sign outbound webhook deliveries" } } } } } }, "x-permissions": [ "vault:write" ] } }, "/vault/{id}/events/subscriptions/{subscriptionId}": { "patch": { "tags": [ "Vault Events" ], "summary": "Update vault webhook subscription", "description": "Updates callback URL, filters, active state, or signing secret for a vault webhook subscription.", "operationId": "updateVaultEventSubscription", "responses": { "200": { "description": "Vault webhook subscription updated successfully" }, "400": { "description": "Webhook payload is invalid or references unknown vault objects" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have write access to vault service" }, "404": { "description": "Vault or subscription not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "callbackUrl": { "type": "string", "format": "uri", "description": "Updated webhook endpoint URL for deliveries" }, "eventTypes": { "type": "array", "items": { "type": "string" }, "description": "Updated event types to deliver for this subscription" }, "objectIds": { "type": "array", "items": { "type": "string" }, "description": "Updated vault object IDs to limit notifications to. Pass an empty array to remove the filter." }, "isActive": { "type": "boolean", "description": "Whether the subscription should continue delivering events" }, "signingSecret": { "type": "string", "description": "Replacement secret used to sign webhook deliveries" }, "clearSigningSecret": { "type": "boolean", "description": "Whether to remove the existing signing secret" } } } } } }, "x-permissions": [ "vault:write" ] }, "delete": { "tags": [ "Vault Events" ], "summary": "Delete vault webhook subscription", "description": "Deactivates a vault webhook subscription.", "operationId": "deleteVaultEventSubscription", "responses": { "200": { "description": "Subscription deleted" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Vault or subscription not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription ID" } ], "x-permissions": [ "vault:write" ] } }, "/vault/{id}/events/subscriptions/{subscriptionId}/test": { "post": { "tags": [ "Vault Events" ], "summary": "Send test webhook event", "description": "Delivers a test event to a single vault webhook subscription. Uses the same payload shape, signature, and retry behavior as production event delivery.", "operationId": "testVaultEventSubscription", "responses": { "200": { "description": "Test event attempted" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid API key" }, "403": { "description": "Insufficient permissions" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Subscription ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Optional event type override for this test" }, "objectId": { "type": "string", "description": "Optional object ID for object-scoped payload testing" }, "payload": { "type": "object", "additionalProperties": true, "description": "Optional additional fields merged into payload.data" } } } } } }, "x-permissions": [ "vault:write" ] } }, "/vault/{id}/folders": { "get": { "tags": [ "Vaults" ], "summary": "List persistent folders", "description": "Lists durable folder paths, including empty folders. Combine with paginated object paths to display imported folders. Requires vault-wide read access; shared vault reads are supported.", "operationId": "listVaultFolders", "responses": { "200": { "description": "Persistent folder paths", "content": { "application/json": { "schema": { "type": "object", "required": [ "folderPaths" ], "properties": { "folderPaths": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "Vault-wide read access required" }, "404": { "description": "Vault not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "vault" ] }, "post": { "tags": [ "Vaults" ], "summary": "Create a persistent folder", "description": "Creates a durable empty folder and missing parents. Metadata only; no S3 objects are created. Requires vault-wide write access and vault ownership.", "operationId": "createVaultFolder", "responses": { "200": { "description": "Folder created", "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "folderPaths" ], "properties": { "path": { "type": "string" }, "folderPaths": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid folder path" }, "401": { "description": "Invalid API key" }, "403": { "description": "Vault-wide write access required" }, "404": { "description": "Vault not found" }, "409": { "description": "Folder exists or folder limit reached" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path" ], "additionalProperties": false, "properties": { "path": { "type": "string", "maxLength": 1024 } } } } } }, "x-permissions": [ "vault" ] }, "patch": { "tags": [ "Vaults" ], "summary": "Rename or move a folder", "description": "Atomically renames or moves a folder, its empty descendants and all descendant object paths. Rejects an existing destination, root and self-descendant moves, and busy objects. Supports vaults with at most 25000 objects. Uses a 5-second lock timeout and 30-second statement timeout. Does not transfer file bytes. Requires vault-wide write access and vault ownership.", "operationId": "moveVaultFolder", "responses": { "200": { "description": "Folder moved", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "newPath": { "type": "string" }, "revision": { "type": "string" }, "folderPaths": { "type": "array", "items": { "type": "string" } }, "movedFiles": { "type": "integer" } } } } } }, "400": { "description": "Invalid or self-descendant move" }, "401": { "description": "Invalid API key" }, "403": { "description": "Vault-wide write access required" }, "404": { "description": "Vault or folder not found" }, "409": { "description": "Destination exists or objects are busy" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path", "newPath" ], "additionalProperties": false, "properties": { "path": { "type": "string" }, "newPath": { "type": "string" }, "expectedRevision": { "type": "string", "description": "Revision from a previous move, for safe Undo." } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/ingest/{objectId}": { "post": { "tags": [ "Vaults" ], "summary": "Ingest vault object", "description": "Triggers ingestion workflow for a vault object to extract text, generate chunks, and create embeddings. For supported file types (PDF, DOCX, PPTX, XLSX, TXT, RTF, XML, HTML, Markdown, CSV/TSV, JSON/YAML/TOML, common source code files, ZIP, audio, video), processing happens asynchronously. ZIP archives always return a processing response, are unpacked recursively up to 5 levels, and each extracted file is created as an independent vault object and ingested via the normal pipeline. For unsupported types (images, etc.), the file is marked as completed immediately without text extraction.", "operationId": "ingestVaultObject", "responses": { "200": { "description": "Ingestion workflow started successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string", "description": "ID of the vault object being processed" }, "workflowId": { "type": "string", "nullable": true, "description": "Workflow run ID for tracking progress. Null for file types that skip processing." }, "status": { "type": "string", "enum": [ "processing", "stored" ], "description": "Current ingestion status. 'stored' for file types without text extraction (no chunks/vectors created)." }, "queued": { "type": "boolean", "description": "True when the document is waiting for ingestion capacity. It starts automatically; workflowId is null until then." }, "message": { "type": "string", "description": "Human-readable status message" } }, "required": [ "objectId", "workflowId", "status", "message" ] }, "example": { "objectId": "obj_abc123", "workflowId": "wf_def456", "status": "processing", "message": "Document ingestion started. Text extraction, chunking, and embedding generation in progress." } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid or missing API key" }, "404": { "description": "Vault or object not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault object ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "callback_url": { "type": "string", "format": "uri", "description": "Optional callback URL for asynchronous workflow completion." }, "page_boundaries": { "type": "array", "uniqueItems": true, "items": { "type": "integer", "minimum": 2 }, "description": "Optional PDF pages that must begin a new chunk segment. Overlap never crosses these boundaries." } }, "additionalProperties": false } } } }, "x-permissions": [ "vault:write" ] } }, "/vault/{id}/memory": { "get": { "tags": [ "Vault Memory" ], "summary": "List vault memory entries", "description": "Retrieve file-backed memory entries stored in a vault.", "operationId": "listVaultMemory", "responses": { "200": { "description": "Vault memory entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "chars": { "type": "integer" }, "max_chars": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "x-permissions": [ "vault" ] }, "post": { "tags": [ "Vault Memory" ], "summary": "Create vault memory entry", "description": "Append a new file-backed memory entry to a vault.", "operationId": "createVaultMemory", "responses": { "200": { "description": "Created memory entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "content" ], "properties": { "type": { "type": "string", "enum": [ "fact", "party", "issue", "deadline", "discovery", "correction", "preference" ] }, "content": { "type": "string" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/memory/{entryId}": { "patch": { "tags": [ "Vault Memory" ], "summary": "Update vault memory entry", "description": "Rewrite a file-backed vault memory entry with updated content, source, or tags.", "operationId": "updateVaultMemory", "responses": { "200": { "description": "Updated memory entry" }, "400": { "description": "Invalid request body" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault or entry not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Memory entry ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "x-permissions": [ "vault" ] }, "delete": { "tags": [ "Vault Memory" ], "summary": "Delete vault memory entry", "description": "Remove a file-backed memory entry from a vault.", "operationId": "deleteVaultMemory", "responses": { "200": { "description": "Memory entry deleted" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault or entry not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Memory entry ID" } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/memory/search": { "post": { "tags": [ "Vault Memory" ], "summary": "Search vault memory", "description": "Search file-backed vault memory using simple full-text matching over content and tags.", "operationId": "searchVaultMemory", "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "content": { "type": "string" }, "source": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/multipart/abort": { "post": { "tags": [ "Vaults" ], "summary": "Abort multipart upload", "description": "Abort a multipart upload and discard uploaded parts (live).", "operationId": "abortVaultMultipartUpload", "responses": { "200": { "description": "Multipart upload aborted successfully" }, "400": { "description": "Multipart upload identifiers are missing or invalid" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have write access to vault service" }, "404": { "description": "Vault or vault object not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "objectId", "uploadId" ], "properties": { "objectId": { "type": "string", "description": "Vault object ID associated with the multipart upload" }, "uploadId": { "type": "string", "description": "Multipart upload ID returned when the upload was initialized" } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/multipart/complete": { "post": { "tags": [ "Vaults" ], "summary": "Complete multipart upload", "description": "Complete a multipart upload by providing the list of part numbers and ETags (live). Single PUT uploads are capped at 5GB; multipart default max is 16GB (configurable).", "operationId": "completeVaultMultipartUpload", "responses": { "200": { "description": "Multipart upload completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "ingest": { "type": "object", "description": "Present when autoIngest was requested", "properties": { "triggered": { "type": "boolean" }, "workflowId": { "type": "string", "nullable": true }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "objectId", "uploadId", "parts", "sizeBytes" ], "properties": { "objectId": { "type": "string" }, "uploadId": { "type": "string" }, "sizeBytes": { "type": "integer", "minimum": 1, "description": "File size in bytes (default max 16GB). Configure via VAULT_MULTIPART_MAX_FILE_SIZE_BYTES." }, "autoIngest": { "type": "boolean", "default": false, "description": "Start ingestion after completion when auto_index is enabled. The ingest response reports whether a workflow was started." }, "parts": { "type": "array", "items": { "type": "object", "required": [ "partNumber", "etag" ], "properties": { "partNumber": { "type": "integer", "minimum": 1 }, "etag": { "type": "string" } } } } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/multipart/init": { "post": { "tags": [ "Vaults" ], "summary": "Initiate multipart upload for vault file", "description": "Initiate a multipart upload for large files (>5GB). Single PUT uploads are capped at 5GB; multipart default max is 16GB (configurable). Multipart uploads are supported in production. Returns an uploadId and object metadata. Use part URLs endpoint to upload parts and complete endpoint to finalize.", "operationId": "initVaultMultipartUpload", "responses": { "200": { "description": "Multipart upload initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string" }, "uploadId": { "type": "string" }, "s3Key": { "type": "string" }, "partSizeBytes": { "type": "integer" }, "partCount": { "type": "integer" }, "file_origin": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Client-defined provenance metadata associated with the file" }, "next_step": { "type": "string" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID to upload the file to" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filename", "contentType", "sizeBytes" ], "properties": { "filename": { "type": "string", "description": "Name of the file to upload" }, "contentType": { "type": "string", "description": "MIME type of the file" }, "sizeBytes": { "type": "integer", "minimum": 1, "description": "File size in bytes (required, default max 16GB). Configure via VAULT_MULTIPART_MAX_FILE_SIZE_BYTES." }, "partSizeBytes": { "type": "integer", "minimum": 5242880, "maximum": 5368709120, "description": "Multipart part size in bytes (min 5MB, max 5GB). Defaults to 64MB." }, "metadata": { "type": "object", "description": "Additional metadata to associate with the file" }, "file_origin": { "type": "object", "additionalProperties": true, "description": "Optional client-defined provenance metadata. Returned with the object and queryable through the object-list API." }, "auto_index": { "type": "boolean", "default": true, "description": "Whether to automatically process and index the file for search" }, "is_ai_generated": { "type": "boolean", "default": false, "description": "Marks the file as AI-generated work product (e.g. uploaded by an agent) rather than a user-provided source document. Persisted on the object and returned by object listings so clients can distinguish provenance." }, "path": { "type": "string", "description": "Optional folder path, excluding the filename, for hierarchy preservation" } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/multipart/part-urls": { "post": { "tags": [ "Vaults" ], "summary": "Get presigned URLs for multipart upload parts", "description": "Generate presigned URLs for individual multipart upload parts (live).", "operationId": "getVaultMultipartPartUrls", "responses": { "200": { "description": "Multipart part URLs generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer" }, "url": { "type": "string" } } } } } } } } }, "400": { "description": "Multipart upload request is invalid or does not match stored upload metadata" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have write access to vault service" }, "404": { "description": "Vault or vault object not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "objectId", "uploadId", "parts" ], "properties": { "objectId": { "type": "string", "description": "Vault object ID associated with the multipart upload" }, "uploadId": { "type": "string", "description": "Multipart upload ID returned when the upload was initialized" }, "parts": { "type": "array", "description": "Multipart parts that need presigned upload URLs", "items": { "type": "object", "required": [ "partNumber", "sizeBytes" ], "properties": { "partNumber": { "type": "integer", "minimum": 1, "description": "1-based multipart part number" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 5368709120, "description": "Part size in bytes (min 5MB except final part, max 5GB)." } } } } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/objects": { "get": { "tags": [ "Vault Objects" ], "summary": "List vault objects", "description": "Retrieve the objects stored in a specific vault, oldest first, including document metadata, ingestion status, and processing statistics. Pass `limit` to page through large vaults: when `pagination.has_more` is true, the response is incomplete and `pagination.next_cursor` fetches the rest.", "operationId": "listVaultObjects", "responses": { "200": { "description": "Successfully retrieved vault objects", "content": { "application/json": { "schema": { "type": "object", "required": [ "vaultId", "objects", "count", "pagination" ], "properties": { "vaultId": { "type": "string", "description": "The ID of the vault" }, "objects": { "type": "array", "items": { "type": "object", "required": [ "id", "filename", "contentType", "ingestionStatus", "createdAt" ], "properties": { "id": { "type": "string", "description": "Unique object identifier" }, "filename": { "type": "string", "description": "Original filename of the uploaded document" }, "contentType": { "type": "string", "description": "MIME type of the document" }, "sizeBytes": { "type": "number", "description": "File size in bytes" }, "folderPath": { "type": "string", "description": "Canonical folder path, excluding the filename even for legacy ZIP imports." }, "path": { "type": "string", "nullable": true, "description": "Optional folder path for hierarchy preservation from source systems" }, "ingestionStatus": { "type": "string", "description": "Processing status of the document" }, "pageCount": { "type": "number", "description": "Number of pages in the document" }, "textLength": { "type": "number", "description": "Total character count of extracted text" }, "chunkCount": { "type": "number", "description": "Number of text chunks created for vectorization" }, "vectorCount": { "type": "number", "description": "Number of vectors generated for semantic search" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Custom tags associated with the document" }, "metadata": { "type": "object", "description": "Custom metadata associated with the document" }, "file_origin": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Client-defined provenance metadata associated with the file" }, "is_ai_generated": { "type": "boolean", "description": "Whether the file was marked as AI-generated work product at upload time" }, "createdAt": { "type": "string", "format": "date-time", "description": "Document upload timestamp" }, "ingestionStartedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When ingestion processing began" }, "ingestionCompletedAt": { "type": "string", "format": "date-time", "description": "Processing completion timestamp" }, "ingestionWorkflowId": { "type": "string", "nullable": true, "description": "Durable workflow run ID for the active or last ingestion attempt. Null while a dispatch claim is being reconciled or when no workflow applies." }, "ingestionError": { "type": "string", "nullable": true, "description": "Failure reason when ingestion status is a failed state" } } } }, "count": { "type": "number", "description": "Number of objects in this response. Equals the vault total only when `pagination.has_more` is false; use `totals.objects` for the total across pages." }, "pagination": { "type": "object", "required": [ "limit", "has_more", "next_cursor" ], "properties": { "limit": { "type": "integer", "nullable": true, "description": "Page size applied, or null when every object was returned." }, "has_more": { "type": "boolean", "description": "Whether more objects exist beyond this page." }, "next_cursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` to fetch the next page. Null on the final page." } } }, "totals": { "type": "object", "description": "Present only with `include_totals=true`. Covers every object matching the filters, across all pages.", "properties": { "objects": { "type": "integer", "description": "Number of matching objects" }, "totalBytes": { "type": "number", "description": "Combined size of matching objects" } } } } }, "example": { "vaultId": "vault_abc123", "objects": [ { "id": "obj_xyz789", "filename": "contract_2024_v2.pdf", "contentType": "application/pdf", "sizeBytes": 2485760, "ingestionStatus": "completed", "pageCount": 15, "textLength": 12450, "chunkCount": 28, "vectorCount": 28, "tags": [ "contract", "2024", "vendor" ], "metadata": { "client": "Acme Corp", "matter": "M-2024-001" }, "file_origin": { "provider": "clio", "matter_id": "matter_123" }, "createdAt": "2024-01-15T10:30:00Z", "ingestionCompletedAt": "2024-01-15T10:32:15Z" } ], "count": 1, "pagination": { "limit": null, "has_more": false, "next_cursor": null } } } } }, "400": { "description": "Invalid vault ID, `file_origin`, `limit` (`INVALID_LIMIT`) or `cursor` (`INVALID_CURSOR`)" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "API key does not have vault service permissions" }, "404": { "description": "Vault not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the vault", "schema": { "type": "string" } }, { "name": "includeUnconfirmed", "in": "query", "required": false, "description": "Include placeholders for uploads that were never completed (awaiting_upload) or were cancelled (aborted). Excluded by default.", "schema": { "type": "boolean", "default": false } }, { "name": "file_origin", "in": "query", "required": false, "description": "JSON-encoded provenance object used as a partial match. For example, {\"provider\":\"clio\"} returns objects whose file_origin contains that value.", "schema": { "type": "string", "example": "{\"provider\":\"clio\"}" } }, { "name": "limit", "in": "query", "required": false, "description": "Objects per page (1-200). Omit to receive every object. Supplying a cursor without a limit uses 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque continuation cursor from `pagination.next_cursor` of the previous page. Must be replayed with the same API key scope and the same `query`, `file_origin` and `includeUnconfirmed` values that produced it.", "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "description": "Case-insensitive substring match on the filename.", "schema": { "type": "string" } }, { "name": "include_totals", "in": "query", "required": false, "description": "When `true`, adds `totals` covering every object matching the filters, not just this page. Request it once per filter change rather than on every page.", "schema": { "type": "boolean" } } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}": { "get": { "tags": [ "Vault Objects" ], "summary": "Get vault object with download URL", "description": "Retrieves metadata for a specific document in a vault and generates a temporary download URL. The download URL expires after 1 hour for security. This endpoint also updates the file size if it wasn't previously calculated.", "operationId": "getVaultObject", "responses": { "200": { "description": "Object metadata and download URL", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "vaultId", "filename", "contentType", "downloadUrl", "expiresIn", "ingestionStatus", "createdAt" ], "properties": { "id": { "type": "string", "description": "Object ID" }, "vaultId": { "type": "string", "description": "Vault ID" }, "filename": { "type": "string", "description": "Original filename" }, "contentType": { "type": "string", "description": "MIME type" }, "sizeBytes": { "type": "integer", "description": "File size in bytes" }, "path": { "type": "string", "nullable": true, "description": "Optional folder path for hierarchy preservation" }, "downloadUrl": { "type": "string", "description": "Presigned S3 download URL" }, "expiresIn": { "type": "integer", "description": "URL expiration time in seconds" }, "ingestionStatus": { "type": "string", "description": "Processing status (pending, processing, completed, failed)" }, "pageCount": { "type": "integer", "description": "Number of pages (for documents)" }, "textLength": { "type": "integer", "description": "Length of extracted text" }, "chunkCount": { "type": "integer", "description": "Number of text chunks created" }, "vectorCount": { "type": "integer", "description": "Number of embedding vectors generated" }, "ingestionError": { "type": "string", "nullable": true, "description": "Error details when ingestion fails" }, "metadata": { "type": "object", "description": "Additional metadata" }, "file_origin": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Client-defined provenance metadata associated with the file" }, "is_ai_generated": { "type": "boolean", "description": "Whether the file was marked as AI-generated work product at upload time" }, "createdAt": { "type": "string", "format": "date-time", "description": "Upload timestamp" }, "transcript_object_id": { "type": "string", "nullable": true, "description": "Object ID of the completed transcript (if available)" } } }, "example": { "id": "obj_abc123", "vaultId": "vault_def456", "filename": "contract_amendment.pdf", "contentType": "application/pdf", "sizeBytes": 2048576, "downloadUrl": "https://s3.amazonaws.com/bucket/key?X-Amz-Algorithm=AWS4-HMAC-SHA256&...", "expiresIn": 3600, "ingestionStatus": "completed", "pageCount": 15, "textLength": 12500, "chunkCount": 32, "vectorCount": 32, "ingestionError": null, "metadata": { "extractedText": true, "language": "en" }, "createdAt": "2024-01-15T10:30:00Z", "transcript_object_id": "obj_transcript_789" } } } }, "400": { "description": "Missing vault ID or object ID" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Vault or object not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object ID within the vault" } ], "x-permissions": [ "vault" ] }, "patch": { "tags": [ "Vault Objects" ], "summary": "Update vault object", "description": "Update a document's filename, folder path, or metadata. Use this to rename files or organize them into virtual folders. The path is a folder, not a complete file path, and is stored separately from the filename.", "operationId": "updateVaultObject", "responses": { "200": { "description": "Object updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Object ID" }, "vaultId": { "type": "string", "description": "Vault ID" }, "filename": { "type": "string", "description": "Updated filename" }, "path": { "type": "string", "nullable": true, "description": "Folder path for hierarchy preservation" }, "contentType": { "type": "string", "description": "MIME type" }, "sizeBytes": { "type": "integer", "description": "File size in bytes" }, "ingestionStatus": { "type": "string", "description": "Processing status" }, "metadata": { "type": "object", "description": "Full metadata object" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp" } } }, "example": { "id": "obj_abc123", "vaultId": "vault_def456", "filename": "deposition-smith-2024.pdf", "path": "/Discovery/Depositions", "contentType": "application/pdf", "sizeBytes": 2048576, "ingestionStatus": "completed", "metadata": { "client": "Smith & Associates" }, "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "description": "Invalid request - no fields to update or invalid field values" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Object not found" }, "409": { "description": "Object is currently being processed and cannot be updated" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object ID to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "New filename for the document (affects display name and downloads)" }, "path": { "type": "string", "nullable": true, "description": "Folder path, excluding the filename, for hierarchy preservation (e.g., '/Discovery/Depositions'). Set to null or empty string to remove." }, "metadata": { "type": "object", "description": "Additional metadata to merge with existing metadata" } } }, "example": { "filename": "deposition-smith-2024.pdf", "path": "/Discovery/Depositions" } } } }, "x-permissions": [ "vault" ] }, "delete": { "tags": [ "Vault Objects" ], "summary": "Delete vault object", "description": "Permanently deletes a document from the vault including all associated vectors, chunks, graph data, and the original file. This operation cannot be undone.", "operationId": "deleteVaultObject", "responses": { "200": { "description": "Object deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "deletedObject": { "type": "object", "properties": { "id": { "type": "string", "description": "Deleted object ID" }, "filename": { "type": "string", "description": "Original filename" }, "sizeBytes": { "type": "integer", "description": "Size of deleted file in bytes" }, "vectorsDeleted": { "type": "integer", "description": "Number of vectors deleted" } } } } }, "example": { "success": true, "deletedObject": { "id": "obj_abc123", "filename": "contract.pdf", "sizeBytes": 1024000, "vectorsDeleted": 28 } } } } }, "400": { "description": "Missing vault ID or object ID" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have vault service access" }, "404": { "description": "Object not found" }, "409": { "description": "Object is currently being processed and cannot be deleted" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object ID to delete" }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true" ] }, "description": "Force delete a stuck document that is still in 'processing' state. Use this if a document got stuck during ingestion (e.g., OCR timeout)." } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}/append": { "post": { "tags": [ "Vault Objects" ], "summary": "Append PDF vault objects onto an existing PDF vault object", "description": "Merges one or more PDF vault objects onto the end of an existing PDF vault object. Sync mode is the default and overwrites the target in place before returning. Async mode returns 202 immediately and reports completion through vault.object.append webhooks. Optionally rewrites citation links in the original target into internal PDF jumps and adds back links on appended pages. The target object’s ingestion state is not affected; appended pages are not searchable.", "operationId": "appendVaultObject", "responses": { "200": { "description": "Target object updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "vaultId": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "checksum": { "type": "string" }, "ingestionStatus": { "type": "string" }, "pageCount": { "type": "integer" }, "appendedPageStart": { "type": "integer", "description": "First 1-indexed page added by this append operation." }, "appendedPageEnd": { "type": "integer", "description": "Last 1-indexed page added by this append operation." }, "objectId": { "type": "string" }, "bates": { "type": "object" }, "metadata": { "type": "object" }, "downloadUrl": { "type": "string" }, "expiresIn": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "202": { "description": "Asynchronous append accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string" }, "vaultId": { "type": "string" }, "workflowId": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "completed", "failed" ] }, "appendedPageStart": { "type": "integer" }, "clientReference": { "type": "string" } } } } } }, "400": { "description": "Invalid request body, more than 20 append objects in sync mode, or unsupported source object format" }, "401": { "description": "Authentication failed - invalid API key" }, "403": { "description": "Access denied - API key lacks vault service permissions" }, "404": { "description": "Vault, target object, or one or more append objects were not found" }, "409": { "description": "Target object is busy or the idempotency key conflicts with another request" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the vault object to append onto" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required when mode is async; stable key for safely retrying the append" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "appendObjectIds" ], "properties": { "mode": { "type": "string", "enum": [ "sync", "async" ], "default": "sync", "description": "Use async to return immediately and receive completion through vault.object.append webhooks." }, "appendObjectIds": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string" }, "description": "Vault object IDs whose pages will be appended onto the target object, in order. Must not include the target object itself. Sync mode accepts at most 20; async mode accepts at most 1000." }, "rewriteLinks": { "type": "boolean", "default": false, "description": "When true, rewrites links in the target object to internal PDF jumps when the URL contains exactly one appended object ID as a standalone query parameter value or decoded path segment." }, "backLinks": { "type": "boolean", "default": false, "description": "Adds back links on appended pages" }, "backLinksText": { "type": "string", "default": "Back to Summary", "maxLength": 120, "description": "Label text for the back link. Used only when backLinks is true and rendered centered at the bottom of each appended page." }, "clientReference": { "type": "string", "maxLength": 200, "description": "Caller-provided correlation value returned in async responses and webhooks." }, "bates": { "type": "object", "description": "Optional Bates stamping for appended source PDFs. Numbering is deterministic across appendObjectIds order and does not stamp the target report pages.", "properties": { "enabled": { "type": "boolean", "default": true }, "prefix": { "type": "string", "default": "", "maxLength": 40 }, "suffix": { "type": "string", "default": "", "maxLength": 20 }, "start": { "type": "integer", "default": 1, "minimum": 1 }, "padTo": { "type": "integer", "default": 0, "minimum": 0, "maximum": 12 } } } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}/chunks": { "get": { "tags": [ "Vault Objects" ], "summary": "Get full object chunks", "description": "Retrieves full extracted chunk text for a processed vault object. Use this after search when a truncated preview is not enough and you need the exact chunk text or adjacent chunks for surrounding context such as tables, exhibit lists, or multi-part passages.", "operationId": "getVaultObjectChunks", "responses": { "200": { "description": "Successfully retrieved full chunk text for the requested range", "content": { "application/json": { "schema": { "type": "object", "required": [ "object_id", "vault_id", "chunks", "total_chunks" ], "properties": { "object_id": { "type": "string", "description": "The object ID" }, "vault_id": { "type": "string", "description": "The vault ID" }, "chunks": { "type": "array", "description": "Full chunk objects for the requested range", "items": { "type": "object", "required": [ "index", "text", "page_start", "page_end", "word_start_index", "word_end_index" ], "properties": { "index": { "type": "integer", "description": "Chunk index within the document" }, "text": { "type": "string", "description": "Full text for the chunk" }, "page_start": { "type": "integer", "nullable": true, "description": "First page covered by the chunk, if page mapping is available" }, "page_end": { "type": "integer", "nullable": true, "description": "Last page covered by the chunk, if page mapping is available" }, "word_start_index": { "type": "integer", "nullable": true, "description": "First OCR word index covered by the chunk, if available" }, "word_end_index": { "type": "integer", "nullable": true, "description": "Last OCR word index covered by the chunk, if available" }, "start_ms": { "type": "integer", "description": "Source media timestamp for the first word in the chunk. Present only for media-backed transcripts with real word timing." }, "end_ms": { "type": "integer", "description": "Source media timestamp for the last word in the chunk. Present only for media-backed transcripts with real word timing." } } } }, "total_chunks": { "type": "integer", "description": "Total number of chunks stored for the object" } } }, "example": { "object_id": "obj_abc123", "vault_id": "vault_def456", "chunks": [ { "index": 12, "text": "Exhibit A lists the devices, serial numbers, and maintenance dates for each unit.", "page_start": 5, "page_end": 5, "word_start_index": 5544, "word_end_index": 6055 }, { "index": 13, "text": "The following rows continue the exhibit table with replacement dates and service notes.", "page_start": 5, "page_end": 6, "word_start_index": 6056, "word_end_index": 6532 }, { "index": 14, "text": "Footnotes on the next page clarify which devices were decommissioned before transfer.", "page_start": 6, "page_end": 6, "word_start_index": 6533, "word_end_index": 6881 } ], "total_chunks": 42 } } } }, "400": { "description": "Bad request - invalid range, missing parameters, or object not processed yet" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - API key lacks vault service access or object scope" }, "404": { "description": "Object or vault not found, or no chunk data is available" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The vault ID containing the document." }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The processed object ID whose chunk text should be retrieved." }, { "name": "start", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "The first chunk index to return (0-based). Defaults to 0." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "The last chunk index to return (inclusive). If omitted, only the `start` chunk is returned. Ranges are limited to 10 chunks." } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}/download": { "get": { "tags": [ "Vault Objects" ], "summary": "Download vault object", "description": "Downloads a file from a vault by redirecting to a short-lived presigned S3 URL. Useful for retrieving contracts, depositions, case files, and other legal documents stored in your vault.", "operationId": "downloadVaultObject", "responses": { "200": { "description": "File downloaded successfully", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Type": { "description": "MIME type of the file", "schema": { "type": "string" } }, "Content-Length": { "description": "Size of the file in bytes", "schema": { "type": "string" } }, "Content-Disposition": { "description": "Attachment header with filename", "schema": { "type": "string" } } } }, "302": { "description": "Redirect to a short-lived presigned download URL", "headers": { "Location": { "description": "Presigned URL for direct object download", "schema": { "type": "string", "format": "uri" } } } }, "400": { "description": "Bad request - missing vault ID or object ID" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - API key lacks vault service permissions" }, "404": { "description": "Not found - vault or object does not exist" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Vault ID", "schema": { "type": "string" } }, { "name": "objectId", "in": "path", "required": true, "description": "Object ID within the vault", "schema": { "type": "string" } } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}/ocr-words": { "get": { "tags": [ "Vault Objects" ], "summary": "Get OCR word bounding boxes", "description": "Retrieves word-level OCR bounding box data for a processed PDF document. Each word includes its text, normalized bounding box coordinates (0-1 range), confidence score, and global word index. Use this data to highlight specific text ranges in a PDF viewer based on word indices from search results.", "operationId": "getVaultObjectOcrWords", "responses": { "200": { "description": "Successfully retrieved OCR word data", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string", "description": "The object ID" }, "pageCount": { "type": "integer", "description": "Total number of pages in the document" }, "totalWords": { "type": "integer", "description": "Total number of words extracted from the document" }, "pages": { "type": "array", "description": "Per-page word data with bounding boxes", "items": { "type": "object", "properties": { "page": { "type": "integer", "description": "Page number (1-indexed)" }, "words": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "The word text" }, "bbox": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "Bounding box [x0, y0, x1, y1] normalized to 0-1 range" }, "confidence": { "type": "number", "nullable": true, "description": "OCR confidence score (0-1)" }, "wordIndex": { "type": "integer", "description": "Global word index across the entire document (0-based)" } } } } } } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the OCR data was extracted" } } }, "example": { "objectId": "obj_abc123", "pageCount": 5, "totalWords": 2500, "pages": [ { "page": 1, "words": [ { "text": "The", "bbox": [ 0.12, 0.71, 0.15, 0.75 ], "confidence": 0.98, "wordIndex": 0 }, { "text": "witness", "bbox": [ 0.16, 0.71, 0.28, 0.75 ], "confidence": 0.99, "wordIndex": 1 } ] } ], "createdAt": "2024-01-15T10:30:00Z" } } } }, "400": { "description": "Bad request - missing parameters or object not processed yet" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - API key lacks vault service access" }, "404": { "description": "Object or vault not found, or no OCR word data available (non-PDF document)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object ID" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter to a specific page number (1-indexed). If omitted, returns all pages." }, { "name": "wordStart", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter to words starting at this index (inclusive). Useful for retrieving words for a specific chunk." }, { "name": "wordEnd", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filter to words ending at this index (inclusive). Useful for retrieving words for a specific chunk." } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}/pages": { "get": { "tags": [ "Vault Objects" ], "summary": "Get object pages", "description": "Retrieves the raw text of a processed vault object split by page. The object must have completed ingestion before pages can be retrieved — for PDFs this requires the OCR pipeline to have finished writing the per-page sidecar, so freshly uploaded PDFs return 400 with the current `ingestionStatus` until processing completes. For PDFs this returns the per-page OCR text. For plain text files (txt, md, source code, court reporter transcripts) the text is split using right-aligned page-number markers when present (preserving the original document numbering, including continuations like Volume 2 starting at page 234), falling back to form-feed (\\f) page-break characters, and finally a single page if neither signal is present. Use the optional `start` and `end` query parameters to fetch a specific inclusive page range. Pages with no text are omitted.", "operationId": "getVaultObjectPages", "responses": { "200": { "description": "Successfully retrieved object pages", "content": { "application/json": { "schema": { "type": "object", "required": [ "pages", "metadata" ], "properties": { "pages": { "type": "array", "description": "Per-page OCR text in ascending page order", "items": { "type": "object", "required": [ "page", "text" ], "properties": { "page": { "type": "integer", "description": "Page number (1-indexed)" }, "text": { "type": "string", "description": "OCR text for this page" } } } }, "metadata": { "type": "object", "required": [ "object_id", "vault_id", "filename", "source", "page_count", "returned_pages" ], "properties": { "object_id": { "type": "string" }, "vault_id": { "type": "string" }, "filename": { "type": "string" }, "source": { "type": "string", "enum": [ "ocr", "txt" ], "description": "Where the page text came from. `ocr` for PDFs (per-page OCR sidecar). `txt` for plain-text files split on form-feed (\\f) characters." }, "page_count": { "type": "integer", "description": "Total number of pages with extracted text in the document" }, "returned_pages": { "type": "integer", "description": "Number of pages returned after applying the range filter" }, "start": { "type": "integer", "nullable": true, "description": "Echoes the start query param if provided" }, "end": { "type": "integer", "nullable": true, "description": "Echoes the end query param if provided" } } } } }, "example": { "pages": [ { "page": 1, "text": "PLAINTIFF’S MOTION FOR SUMMARY JUDGMENT..." }, { "page": 2, "text": "STATEMENT OF UNDISPUTED FACTS..." } ], "metadata": { "object_id": "obj_abc123", "vault_id": "vault_def456", "filename": "motion_for_summary_judgment.pdf", "source": "ocr", "page_count": 15, "returned_pages": 2, "start": 1, "end": 2 } } } } }, "400": { "description": "Bad request - invalid range or object not processed" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - API key lacks vault service access" }, "404": { "description": "Object or vault not found, or no per-page OCR text available (non-PDF document)" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object ID" }, { "name": "start", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "First page to return (inclusive, 1-indexed). If omitted, starts at the first page with text." }, { "name": "end", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Last page to return (inclusive, 1-indexed). If omitted, returns through the last page with text." } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}/presigned-url": { "post": { "tags": [ "Vault Objects" ], "summary": "Generate presigned URL for object operations", "description": "Generate presigned URLs for direct S3 operations (GET, PUT, DELETE, HEAD) on vault objects. This allows secure, time-limited access to files without proxying through the API. Essential for large document uploads/downloads in legal workflows.", "operationId": "generateObjectPresignedUrl", "responses": { "200": { "description": "Presigned URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string", "description": "The object identifier" }, "vaultId": { "type": "string", "description": "The vault identifier" }, "filename": { "type": "string", "description": "Original filename" }, "s3Key": { "type": "string", "description": "S3 object key" }, "operation": { "type": "string", "description": "The operation type" }, "presignedUrl": { "type": "string", "description": "The presigned URL for direct S3 access" }, "expiresIn": { "type": "integer", "description": "URL expiration time in seconds" }, "expiresAt": { "type": "string", "format": "date-time", "description": "URL expiration timestamp" }, "instructions": { "type": "object", "description": "Usage instructions and examples" }, "metadata": { "type": "object", "properties": { "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "bucket": { "type": "string" }, "region": { "type": "string" } } } } } } } }, "400": { "description": "Invalid request parameters or operation" }, "401": { "description": "Invalid or missing API key" }, "403": { "description": "API key lacks vault service permissions" }, "404": { "description": "Vault or object not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the vault" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the object" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "GET", "PUT", "DELETE", "HEAD" ], "default": "GET", "description": "The S3 operation to generate URL for" }, "expiresIn": { "type": "integer", "minimum": 60, "maximum": 604800, "default": 3600, "description": "URL expiration time in seconds (1 minute to 7 days)" }, "contentType": { "type": "string", "description": "Content type for PUT operations (optional, defaults to object's content type)" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 5368709120, "description": "File size in bytes (optional, max 5GB for single PUT uploads). When provided for PUT operations, enforces exact file size at S3 level." } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/{objectId}/text": { "get": { "tags": [ "Vault Objects" ], "summary": "Get object text", "description": "Retrieves the full extracted text content from a processed vault object, page-numbered (--- Page N --- markers) when the source document is paginated. Useful for document review, analysis, or export. The object must have completed processing before text can be retrieved.", "operationId": "getVaultObjectText", "responses": { "200": { "description": "Successfully retrieved object text", "content": { "application/json": { "schema": { "type": "object", "required": [ "text", "metadata" ], "properties": { "text": { "type": "string", "description": "Full concatenated text content from all chunks" }, "metadata": { "type": "object", "required": [ "object_id", "vault_id", "filename", "chunk_count", "length" ], "properties": { "object_id": { "type": "string", "description": "The object ID" }, "vault_id": { "type": "string", "description": "The vault ID" }, "filename": { "type": "string", "description": "Original filename of the document" }, "chunk_count": { "type": "integer", "description": "Number of text chunks the document was split into" }, "length": { "type": "integer", "description": "Total character count of the extracted text" }, "ingestion_completed_at": { "type": "string", "format": "date-time", "description": "When the document processing completed" } } } } }, "example": { "text": "PLAINTIFF'S MOTION FOR SUMMARY JUDGMENT\n\nTO THE HONORABLE COURT:\n\nPlaintiff respectfully moves this Court for summary judgment on all claims...\n\n[Additional contract text continues...]", "metadata": { "object_id": "obj_abc123", "vault_id": "vault_def456", "filename": "motion_for_summary_judgment.pdf", "chunk_count": 15, "length": 12847, "ingestion_completed_at": "2024-01-15T10:30:00Z" } } } } }, "400": { "description": "Bad request - missing parameters or object not processed yet" }, "401": { "description": "Unauthorized - invalid API key" }, "403": { "description": "Forbidden - API key lacks vault service access" }, "404": { "description": "Object or vault not found, or no text chunks available" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The object ID" } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/merge": { "post": { "tags": [ "Vault Objects" ], "summary": "Create a searchable PDF from ordered vault objects", "description": "Starts an asynchronous merge that creates a new PDF vault object. Source objects are unchanged. Missing searchable PDF renditions are generated on demand before combining. Completion is reported through vault.object.merge webhooks.", "operationId": "mergeVaultObjects", "responses": { "202": { "description": "Merge accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string" }, "workflowId": { "type": "string" }, "status": { "type": "string", "enum": [ "processing" ] }, "clientReference": { "type": "string" } } } } } }, "400": { "description": "Invalid request or unsupported source objects" }, "401": { "description": "Invalid API key" }, "403": { "description": "Vault write access required" }, "404": { "description": "Vault or source object not found" }, "409": { "description": "Idempotency conflict or source metadata not ready" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Stable key for safely retrying the same merge request" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sourceObjectIds", "filename", "sourceRendition" ], "properties": { "sourceObjectIds": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string" }, "description": "Source object IDs in output order" }, "filename": { "type": "string", "maxLength": 255, "description": "Output PDF filename" }, "sourceRendition": { "type": "string", "enum": [ "original", "searchable_pdf" ], "default": "searchable_pdf" }, "clientReference": { "type": "string", "maxLength": 200 }, "bates": { "type": "object", "properties": { "prefix": { "type": "string", "maxLength": 40, "default": "" }, "suffix": { "type": "string", "maxLength": 20, "default": "" }, "start": { "type": "integer", "minimum": 1, "default": 1 }, "padTo": { "type": "integer", "minimum": 0, "maximum": 12, "default": 0 } } } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/move": { "post": { "tags": [ "Vault Objects" ], "summary": "Move or copy objects between accessible vaults", "description": "Copies storage and search data without downloading the file through the client. Moves preserve object IDs; copies return new IDs. Extracted ZIP children travel with their parent. Retry failed objects with the same Idempotency-Key; successful objects are replayed without transfer. Object ID order does not affect the key.", "operationId": "transferVaultObjects", "responses": { "200": { "description": "Per-object transfer results, including any extracted children", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceVaultId": { "type": "string" }, "destinationVaultId": { "type": "string" }, "mode": { "type": "string" }, "results": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid API key" }, "403": { "description": "Write access required" }, "404": { "description": "Vault not found or access denied" }, "409": { "description": "Idempotency conflict or transfer already in progress" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Source vault ID" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destinationVaultId", "objectIds", "mode" ], "properties": { "destinationVaultId": { "type": "string" }, "objectIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "move", "copy" ] }, "path": { "type": "string", "nullable": true } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/objects/organize": { "post": { "tags": [ "Vault Objects" ], "summary": "Move files to a folder", "description": "Atomically moves up to 500 files to a folder. Authoritative transcription results follow source media. Selecting a transcription result requires selecting its source media too. Source and destination folders remain durable even when empty. Metadata only; requires vault-wide write access and vault ownership.", "operationId": "moveVaultFiles", "responses": { "200": { "description": "Files moved", "content": { "application/json": { "schema": { "type": "object", "properties": { "folderPaths": { "type": "array", "items": { "type": "string" } }, "moves": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "previousPath": { "type": "string" }, "path": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid selection or path" }, "401": { "description": "Invalid API key" }, "403": { "description": "Vault-wide write access required" }, "404": { "description": "Vault or file not found" }, "409": { "description": "Files changed or are busy" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "objectIds", "path" ], "additionalProperties": false, "properties": { "objectIds": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "string" } }, "path": { "type": "string" }, "expectedPaths": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Optional current folder preconditions for the supplied object IDs only. Automatically included transcription results do not require entries; supplied result entries are checked." } } }, { "type": "object", "required": [ "moves" ], "additionalProperties": false, "properties": { "moves": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "required": [ "id", "path", "expectedPath" ], "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "expectedPath": { "type": "string" } } }, "description": "Restore confirmed move receipts with optimistic concurrency checks. Include every receipt for each media/transcription family. Cannot combine with objectIds or path." } } } ] } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/search": { "post": { "tags": [ "Vaults" ], "summary": "Search vault documents", "description": "Search across vault documents using hybrid vector + BM25 search (default), fast vector similarity search, or a simple vector fallback. Returns matching chunks and their source documents.", "operationId": "searchVault", "responses": { "200": { "description": "Search results with relevant documents and contextual answers", "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "description": "Search method used" }, "query": { "type": "string", "description": "Original search query" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "pageCount": { "type": "integer" }, "textLength": { "type": "integer" }, "chunkCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "ingestionCompletedAt": { "type": "string", "format": "date-time" } } } }, "chunks": { "type": "array", "description": "Relevant text chunks with similarity scores and page locations", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Preview of the chunk text (up to 500 characters)" }, "filename": { "type": "string", "nullable": true, "description": "Filename of the chunk's source document; null when the vector's object ID no longer matches a vault object (stale index entry)" }, "object_id": { "type": "string", "description": "ID of the source document" }, "chunk_index": { "type": "integer", "description": "Index of the chunk within the document (0-based)" }, "page_start": { "type": "integer", "nullable": true, "description": "PDF page number where the chunk begins (1-indexed). Null for non-PDF documents or documents ingested before page tracking was added." }, "page_end": { "type": "integer", "nullable": true, "description": "PDF page number where the chunk ends (1-indexed). Null for non-PDF documents or documents ingested before page tracking was added." }, "word_start_index": { "type": "integer", "nullable": true, "description": "Starting word index (0-based) in the OCR word list. Use with GET /vault/:id/objects/:objectId/ocr-words to retrieve bounding boxes for highlighting." }, "word_end_index": { "type": "integer", "nullable": true, "description": "Ending word index (0-based) in the OCR word list. Use with GET /vault/:id/objects/:objectId/ocr-words to retrieve bounding boxes for highlighting." }, "start_ms": { "type": "integer", "description": "Source media timestamp for the first word in the chunk. Present only for media-backed transcripts with real word timing." }, "end_ms": { "type": "integer", "description": "Source media timestamp for the last word in the chunk. Present only for media-backed transcripts with real word timing." }, "distance": { "type": "number", "description": "Vector similarity distance (lower is more similar)" }, "score": { "type": "number", "description": "Relevance score (deprecated, use distance or hybridScore)" }, "source": { "type": "string", "description": "Source identifier (deprecated, use object_id)" } } } }, "vault_id": { "type": "string", "description": "ID of the searched vault" } } } } } }, "400": { "description": "Invalid request - missing vault ID or query" }, "401": { "description": "Invalid API key" }, "404": { "description": "Vault not found or access denied" }, "500": { "description": "Search service error" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique identifier of the vault to search" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Search query or question to find relevant documents" }, "method": { "type": "string", "enum": [ "hybrid", "fast", "vector" ], "default": "hybrid", "description": "Search method: 'hybrid' for combined vector + keyword ranking (default), 'fast' for quick vector similarity search, 'vector' for a simple document listing fallback" }, "topK": { "type": "integer", "default": 10, "minimum": 1, "maximum": 100, "description": "Maximum number of results to return. Hybrid search supports 1 to 50; other methods may support up to 100." }, "filters": { "type": "object", "description": "Filters to narrow search results to specific documents", "properties": { "object_id": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Filter to specific document(s) by object ID. Accepts a single ID or array of IDs." }, "page_range": { "type": "object", "required": [ "start" ], "additionalProperties": false, "properties": { "start": { "type": "integer", "minimum": 1 }, "end": { "type": "integer", "minimum": 1 } }, "description": "Restrict vector-backed retrieval to chunks wholly contained in this inclusive PDF page range. Supported by vector, hybrid, and fast methods." } }, "additionalProperties": true } } } } } }, "x-permissions": [ "vault:read" ] } }, "/vault/{id}/shares": { "get": { "tags": [ "Vaults" ], "summary": "List vault shares", "description": "List all cross-org shares for a vault. Only the vault owner can list shares.", "operationId": "listVaultShares", "responses": { "200": { "description": "List of shares", "content": { "application/json": { "schema": { "type": "object", "properties": { "shares": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "vault_id": { "type": "string" }, "target_org_id": { "type": "string" }, "permission": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Invalid API key" }, "403": { "description": "No vault access" }, "404": { "description": "Vault not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "x-permissions": [ "vault" ] }, "post": { "tags": [ "Vaults" ], "summary": "Create a vault share", "description": "Grant another organization read-only access to this vault. Only the vault owner can create shares. Idempotent: re-sharing to the same org updates the existing share.", "operationId": "createVaultShare", "responses": { "200": { "description": "Share created or updated successfully" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid API key" }, "403": { "description": "No vault access or not the vault owner" }, "404": { "description": "Vault not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_org_id" ], "properties": { "target_org_id": { "type": "string", "description": "The organization ID to grant access to" }, "permission": { "type": "string", "enum": [ "read" ], "default": "read", "description": "Permission level (only \"read\" is supported currently)" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration timestamp for the share" } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/shares/{shareId}": { "delete": { "tags": [ "Vaults" ], "summary": "Revoke a vault share", "description": "Revoke cross-org access to a vault. Only the vault owner can revoke shares.", "operationId": "deleteVaultShare", "responses": { "200": { "description": "Share revoked successfully" }, "401": { "description": "Invalid API key" }, "403": { "description": "No vault access" }, "404": { "description": "Vault or share not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "shareId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Share ID to revoke" } ], "x-permissions": [ "vault" ] } }, "/vault/{id}/upload": { "post": { "tags": [ "Vaults" ], "summary": "Generate presigned upload URL for vault file", "description": "Generate a presigned URL for uploading files directly to a vault's S3 storage. After uploading to S3, confirm the upload result via POST /vault/:vaultId/upload/:objectId/confirm before triggering ingestion.", "operationId": "generateVaultUploadUrl", "responses": { "200": { "description": "Upload URL generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "objectId": { "type": "string", "description": "Unique identifier for the uploaded object" }, "uploadUrl": { "type": "string", "nullable": true, "description": "Presigned URL for uploading the file" }, "alreadyUploaded": { "type": "boolean", "description": "True when this idempotency key already identifies a confirmed upload" }, "expiresIn": { "type": "number", "description": "URL expiration time in seconds" }, "s3Key": { "type": "string", "description": "S3 object key for the file" }, "path": { "type": "string", "nullable": true, "description": "Folder path for hierarchy if provided" }, "auto_index": { "type": "boolean", "description": "Whether the file will be automatically indexed" }, "is_ai_generated": { "type": "boolean", "description": "Whether the file is marked as AI-generated work product" }, "file_origin": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Client-defined provenance metadata associated with the file" }, "enableIndexing": { "type": "boolean", "description": "Whether the vault supports indexing. False for storage-only vaults." }, "instructions": { "type": "object", "nullable": true, "properties": { "method": { "type": "string" }, "headers": { "type": "object" }, "note": { "type": "string" } } }, "next_step": { "type": "string", "nullable": true, "description": "Next API endpoint to call for processing" } } }, "example": { "objectId": "cm123abc456", "uploadUrl": "https://vault-bucket.s3.amazonaws.com/objects/cm123abc456/contract.pdf?X-Amz-Algorithm=...", "alreadyUploaded": false, "expiresIn": 3600, "s3Key": "objects/cm123abc456/contract.pdf", "auto_index": true, "enableIndexing": true, "instructions": { "method": "PUT", "headers": { "Content-Type": "application/pdf" }, "note": "Upload your file to the uploadUrl using PUT request. After upload completes, call POST /vault/:vaultId/upload/:objectId/confirm to record the result, then call POST /vault/:vaultId/ingest/:objectId to trigger processing." }, "next_step": "POST /vault/vault_789/ingest/cm123abc456" } } } }, "400": { "description": "Invalid request - missing required fields or invalid vault ID" }, "401": { "description": "Authentication failed - invalid API key" }, "403": { "description": "Access denied - API key lacks vault service permissions" }, "404": { "description": "Vault not found or access denied" }, "409": { "description": "Idempotency key conflict" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID to upload the file to" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Optional stable key for safely retrying upload initialization" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filename", "contentType" ], "properties": { "filename": { "type": "string", "description": "Name of the file to upload" }, "contentType": { "type": "string", "description": "MIME type of the file (e.g., application/pdf, image/jpeg)" }, "metadata": { "type": "object", "description": "Additional metadata to associate with the file" }, "file_origin": { "type": "object", "additionalProperties": true, "description": "Optional client-defined provenance metadata. Returned with the object and queryable through the object-list API." }, "auto_index": { "type": "boolean", "default": true, "description": "Whether to automatically process and index the file for search" }, "is_ai_generated": { "type": "boolean", "default": false, "description": "Marks the file as AI-generated work product (e.g. uploaded by an agent) rather than a user-provided source document. Persisted on the object and returned by object listings so clients can distinguish provenance." }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 5368709120, "description": "File size in bytes (optional, including zero, max 5GB for single PUT uploads). When provided, enforces exact file size at S3 level. Empty files can be stored and transferred, but cannot be ingested." }, "path": { "type": "string", "description": "Optional folder path, excluding the filename, for hierarchy preservation. Allows integrations to maintain source folder structure from systems like NetDocs, Clio, or Smokeball. Example: '/Discovery/Depositions/2024'" } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/{id}/upload/{objectId}/confirm": { "post": { "tags": [ "Vaults" ], "summary": "Confirm vault upload result", "description": "Confirm whether a direct-to-S3 vault upload succeeded or failed. This endpoint emits vault.upload.completed or vault.upload.failed events and is idempotent for repeated confirmations. Conditional fields: when success=true, sizeBytes is required; when success=false, errorCode and errorMessage are required. These rules are enforced server-side with specific 400 responses.", "operationId": "confirmVaultUpload", "responses": { "200": { "description": "Confirmation recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "vaultId": { "type": "string" }, "objectId": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "alreadyConfirmed": { "type": "boolean" }, "ingest": { "type": "object", "description": "Present when autoIngest was requested on a successful confirmation", "properties": { "triggered": { "type": "boolean" }, "workflowId": { "type": "string", "nullable": true }, "error": { "type": "string" }, "statusCode": { "type": "integer" } } } } }, "example": { "vaultId": "vault_123", "objectId": "obj_456", "status": "completed", "alreadyConfirmed": false } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Authentication failed - invalid API key" }, "403": { "description": "Access denied - API key lacks vault service permissions" }, "404": { "description": "Vault or object not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault ID" }, { "name": "objectId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault object ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "title": "VaultConfirmUpload", "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether the upload succeeded" }, "sizeBytes": { "type": "integer", "minimum": 0, "maximum": 5368709120, "description": "Uploaded file size in bytes, including zero. Required when success=true and verified against S3. Empty files can be stored and transferred, but cannot be ingested." }, "etag": { "type": "string", "description": "S3 ETag for the uploaded object (optional if client cannot access ETag header). Only meaningful when success=true." }, "autoIngest": { "type": "boolean", "default": false, "description": "When true and the object was uploaded with auto_index, trigger ingestion immediately after a successful confirmation (no separate ingest call needed). The ingest outcome is reported in the `ingest` response field; an ingest failure does not fail the confirmation." }, "errorCode": { "type": "string", "description": "Client-side error code. Required when success=false." }, "errorMessage": { "type": "string", "description": "Client-side error message. Required when success=false." } } } } } }, "x-permissions": [ "vault" ] } }, "/vault/groups": { "get": { "tags": [ "Vaults" ], "summary": "List vault groups", "description": "Lists vault groups visible to the authenticated organization. Group-scoped API keys only receive groups within their allowed scope.", "operationId": "listVaultGroups", "responses": { "200": { "description": "Vault groups retrieved successfully" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to vault service" } }, "x-permissions": [ "vault" ] }, "post": { "tags": [ "Vaults" ], "summary": "Create vault group", "description": "Creates a vault group for organizing vaults and applying group-scoped access controls. Group-scoped API keys cannot create or manage vault groups.", "operationId": "createVaultGroup", "responses": { "200": { "description": "Vault group created successfully" }, "400": { "description": "Vault group name is missing or invalid" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key cannot manage vault groups" }, "409": { "description": "A vault group with this name already exists" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Human-readable name for the vault group" }, "description": { "type": "string", "description": "Optional description of the vault group purpose" } } } } } }, "x-permissions": [ "vault:write" ] } }, "/vault/groups/{groupId}": { "patch": { "tags": [ "Vaults" ], "summary": "Update vault group", "description": "Updates a vault group for the authenticated organization. Only provided fields are changed, and setting description to null removes the current description.", "operationId": "updateVaultGroup", "responses": { "200": { "description": "Vault group updated successfully" }, "400": { "description": "Vault group ID is missing or no valid fields were provided" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key cannot manage vault groups" }, "404": { "description": "Vault group not found" }, "409": { "description": "A vault group with this name already exists" } }, "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault group ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New human-readable name for the vault group" }, "description": { "type": "string", "nullable": true, "description": "Updated vault group description. Pass null to remove the current description." } } } } } }, "x-permissions": [ "vault:write" ] }, "delete": { "tags": [ "Vaults" ], "summary": "Delete vault group", "description": "Soft-deletes a vault group that no longer has any active vaults assigned. This operation is blocked when the group still contains vaults.", "operationId": "deleteVaultGroup", "responses": { "200": { "description": "Vault group deleted successfully" }, "400": { "description": "Vault group ID is required" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key cannot manage vault groups" }, "404": { "description": "Vault group not found" }, "409": { "description": "Vault group still has assigned vaults" } }, "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Vault group ID" } ], "x-permissions": [ "vault:write" ] } }, "/vault/health": { "get": { "tags": [ "Vaults" ], "summary": "Health check", "description": "Unauthenticated health check for the Vault service.", "operationId": "getVaultHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "vault" } } } } } } }, "/vault/ocr/callback": { "post": { "tags": [ "Vaults" ], "summary": "Receive OCR callback relay events", "description": "Public relay endpoint for OCR completion callbacks. Validates a signed callback target and forwards the payload to the suspended workflow webhook.", "operationId": "vaultOcrCallbackRelay", "responses": { "200": { "description": "Callback forwarded successfully" }, "400": { "description": "Missing or invalid relay parameters" }, "401": { "description": "Invalid relay signature" }, "410": { "description": "Relay signature expired" }, "502": { "description": "Forwarding to workflow webhook failed" } }, "parameters": [ { "name": "target", "in": "query", "required": true, "description": "Signed workflow webhook URL to forward the callback to", "schema": { "type": "string" } }, { "name": "objectId", "in": "query", "required": true, "description": "Vault object ID associated with the OCR workflow", "schema": { "type": "string" } }, { "name": "expiresAt", "in": "query", "required": true, "description": "ISO timestamp after which the relay request is rejected", "schema": { "type": "string", "format": "date-time" } }, { "name": "signature", "in": "query", "required": true, "description": "HMAC signature for the relay parameters", "schema": { "type": "string" } } ] } }, "/voice/boost-list/extract": { "post": { "tags": [ "Voice" ], "summary": "Extract boost list from documents", "description": "Extracts a categorized word boost list from vault documents or raw text using LLM entity extraction. The resulting list can be passed as `word_boost` to the transcription endpoint for improved accuracy.", "operationId": "extractBoostList", "responses": { "200": { "description": "Boost list extracted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "category": { "type": "string" }, "boost_param": { "type": "string", "enum": [ "low", "default", "high" ] } } } }, "source": { "type": "string", "enum": [ "document", "text" ] }, "source_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request - missing required fields" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - lacks voice service permissions" }, "404": { "description": "Vault or objects not found" } }, "requestBody": { "description": "Source documents or text for entity extraction", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vault_id": { "type": "string", "description": "Vault ID containing the source documents (use with object_ids)" }, "object_ids": { "type": "array", "items": { "type": "string" }, "description": "Object IDs of documents to extract entities from (PDFs, text files)" }, "text": { "type": "string", "description": "Raw text input for entity extraction (alternative to vault documents)" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "person", "organization", "legal_term", "medical", "citation", "email" ] }, "description": "Optional filter for entity categories to extract" } } } } } }, "x-permissions": [ "voice", "transcription" ] } }, "/voice/boost-list/generate": { "post": { "tags": [ "Voice" ], "summary": "Generate boost list from transcript", "description": "Generates a categorized word boost list from a completed transcription job. Extracts entities from the pass-1 transcript for use as `word_boost` in a second transcription pass.", "operationId": "generateBoostList", "responses": { "200": { "description": "Boost list generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "word": { "type": "string" }, "category": { "type": "string" }, "boost_param": { "type": "string", "enum": [ "low", "default", "high" ] } } } }, "source": { "type": "string", "enum": [ "transcript" ] }, "source_ids": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Bad request or job not completed" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Transcription job not found" } }, "requestBody": { "description": "Transcription job reference for entity extraction", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transcription_job_id" ], "properties": { "transcription_job_id": { "type": "string", "description": "Completed pass-1 transcription job ID (tr_...)" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "person", "organization", "legal_term", "medical", "citation", "email" ] }, "description": "Optional filter for entity categories to extract" } } } } } }, "x-permissions": [ "voice", "transcription" ] } }, "/voice/health": { "get": { "tags": [ "Voice" ], "summary": "Health check", "description": "Unauthenticated health check for the Voice service.", "operationId": "getVoiceHealth", "responses": { "200": { "description": "Service is reachable", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" } }, "required": [ "status", "service" ] }, "example": { "status": "ok", "service": "voice" } } } } } } }, "/voice/streaming/url": { "get": { "tags": [ "Voice" ], "summary": "Get streaming transcription WebSocket URL", "description": "Returns the WebSocket URL and connection details for real-time audio transcription. The returned URL can be used to establish a WebSocket connection for streaming audio data and receiving transcribed text in real-time.\n\n**Audio Requirements:**\n- Sample Rate: 16kHz\n- Encoding: PCM 16-bit little-endian\n- Channels: Mono (1 channel)\n\n**Pricing:** $0.01 per minute ($0.60 per hour)", "operationId": "getStreamingUrl", "responses": { "200": { "description": "WebSocket connection details returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Base WebSocket URL for streaming transcription" }, "connect_url": { "type": "string", "description": "Complete WebSocket URL with authentication token" }, "protocol": { "type": "string", "description": "Connection protocol" }, "audio_format": { "type": "object", "properties": { "sample_rate": { "type": "integer", "description": "Required audio sample rate in Hz" }, "encoding": { "type": "string", "description": "Required audio encoding format" }, "channels": { "type": "integer", "description": "Number of audio channels" } } }, "pricing": { "type": "object", "properties": { "per_minute": { "type": "number", "description": "Cost per minute of transcription" }, "per_hour": { "type": "number", "description": "Cost per hour of transcription" }, "currency": { "type": "string", "description": "Currency for pricing" } } } } }, "example": { "url": "wss://casemark-ai--websocket-stream-helper-fastapi-app.modal.run/ws", "connect_url": "wss://casemark-ai--websocket-stream-helper-fastapi-app.modal.run/ws?token=cm_1234567890abcdef", "protocol": "websocket", "audio_format": { "sample_rate": 16000, "encoding": "pcm_s16le", "channels": 1 }, "pricing": { "per_minute": 0.01, "per_hour": 0.6, "currency": "USD" } } } } }, "401": { "description": "Authentication failed - invalid API key" }, "403": { "description": "Insufficient permissions - API key does not have access to voice/transcription/streaming services" } }, "x-permissions": [ "voice", "transcription", "streaming" ] } }, "/voice/transcription": { "post": { "tags": [ "Voice" ], "summary": "Create transcription job", "description": "Creates an asynchronous transcription job for audio or video files. Supports two modes:\n\n**Vault-based (recommended)**: Pass `vault_id` and `object_id` to transcribe media from your vault. Large videos are converted to an internal MP3 derivative before transcription while the original video remains the transcript source. The transcript is automatically saved back to the vault when complete.\n\n**Direct URL (legacy)**: Pass `audio_url` for direct transcription without automatic storage.", "operationId": "createTranscription", "responses": { "200": { "description": "Transcription job created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique transcription job ID" }, "status": { "type": "string", "description": "Current status of the transcription job", "enum": [ "queued", "preprocessing", "processing", "completed", "error" ] }, "vault_id": { "type": "string", "description": "Vault ID (only for vault-based transcription)" }, "source_object_id": { "type": "string", "description": "Original source media object ID (only for vault-based transcription)" }, "input_object_id": { "type": "string", "description": "Object submitted to the speech provider. For large videos, this is an internal audio derivative." } } }, "example": { "id": "tr_abc123def456", "status": "processing", "vault_id": "vault_xyz789", "source_object_id": "obj_audio_123" } } } }, "400": { "description": "Bad request - missing required fields or invalid parameters" }, "401": { "description": "Unauthorized - invalid or missing API key" }, "403": { "description": "Forbidden - API key lacks voice/transcription service permissions" }, "404": { "description": "Vault or object not found" }, "409": { "description": "Object is already being transcribed, or the existing job has a different disfluencies setting. The conflict message identifies the incompatible job." }, "502": { "description": "Transcription provider temporarily unavailable (e.g., billing or out-of-funds error)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "null", "description": "Always null for provider errors" }, "status": { "type": "string", "enum": [ "error" ], "description": "Error status indicating provider failure" }, "error": { "type": "string", "description": "Human-readable error message" } }, "required": [ "id", "status", "error" ] }, "example": { "id": null, "status": "error", "error": "Transcription service temporarily unavailable due to a provider billing issue. Please try again later." } } } } }, "requestBody": { "description": "Transcription job configuration", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vault_id": { "type": "string", "description": "Vault ID containing the audio file (use with object_id)" }, "object_id": { "type": "string", "description": "Object ID of the audio file in the vault (use with vault_id)" }, "format": { "type": "string", "enum": [ "json", "text" ], "default": "json", "description": "Output format for the transcript when using vault mode" }, "audio_url": { "type": "string", "description": "URL of the audio file to transcribe (legacy mode, no auto-storage)" }, "language_code": { "type": "string", "description": "Language code (e.g., 'en_us', 'es', 'fr'). If not specified, language will be auto-detected" }, "speaker_labels": { "type": "boolean", "description": "Enable speaker identification and labeling", "default": false }, "speakers_expected": { "type": "integer", "description": "Expected number of speakers (improves accuracy when known)" }, "auto_highlights": { "type": "boolean", "description": "Automatically extract key phrases and topics", "default": false }, "content_safety": { "type": "boolean", "description": "Enable content moderation and safety labeling", "default": false }, "language_detection": { "type": "boolean", "description": "Enable automatic language detection", "default": false }, "speech_models": { "type": "array", "items": { "type": "string" }, "description": "Priority-ordered speech models to use", "default": [ "universal-3-5-pro" ] }, "punctuate": { "type": "boolean", "description": "Add punctuation to the transcript", "default": true }, "format_text": { "type": "boolean", "description": "Format text with proper capitalization", "default": true }, "disfluencies": { "type": "boolean", "description": "Preserve filler words such as um and uh in English transcription", "default": false }, "word_boost": { "type": "array", "items": { "type": "string" }, "description": "Custom vocabulary words to boost (e.g., legal terms)" }, "boost_param": { "type": "string", "enum": [ "low", "default", "high" ], "description": "How much to boost custom vocabulary" } } } } } }, "x-permissions": [ "voice", "transcription" ] } }, "/voice/transcription/{id}": { "get": { "tags": [ "Voice" ], "summary": "Get transcription status", "description": "Retrieve the status and result of an audio transcription job. For vault-based jobs, returns status and result_object_id when complete. For legacy direct URL jobs, returns the full transcription data.", "operationId": "getTranscription", "responses": { "200": { "description": "Transcription status and result", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique transcription job ID" }, "status": { "type": "string", "enum": [ "queued", "preprocessing", "processing", "completed", "failed" ], "description": "Current status of the transcription job" }, "vault_id": { "type": "string", "description": "Vault ID (vault-based jobs only)" }, "source_object_id": { "type": "string", "description": "Original source media object ID (vault-based jobs only)" }, "input_object_id": { "type": "string", "description": "Media object submitted to the speech provider. May be an internal audio derivative for large videos." }, "result_object_id": { "type": "string", "description": "Result transcript object ID (vault-based jobs, when completed)" }, "audio_duration": { "type": "number", "description": "Duration of the audio file in seconds" }, "word_count": { "type": "integer", "description": "Number of words in the transcript" }, "confidence": { "type": "number", "description": "Overall confidence score (0-100)" }, "error": { "type": "string", "description": "Error message (only present when status is failed)" }, "text": { "type": "string", "description": "Full transcription text (only included when include_text=true for vault-based jobs, or for legacy direct URL jobs)" }, "words": { "type": "array", "description": "Word-level timestamps (legacy direct URL jobs only)" } }, "required": [ "id", "status" ] }, "example": { "id": "tr_abc123def456", "status": "completed", "vault_id": "vault_xyz789", "source_object_id": "obj_audio_123", "result_object_id": "obj_transcript_456", "audio_duration": 1847.3, "word_count": 4521, "confidence": 94 } } } }, "400": { "description": "Invalid request - missing or invalid transcript ID" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to voice/transcription service" }, "404": { "description": "Transcription not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The transcription job ID (tr_xxx for vault-based, or AssemblyAI ID for legacy)", "example": "tr_abc123def456" }, { "name": "include_text", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Include full transcript text in response for vault-based jobs (default: false)", "example": "true" } ], "x-permissions": [ "voice", "transcription" ] }, "delete": { "tags": [ "Voice" ], "summary": "Delete transcription", "description": "Deletes a transcription job. For managed vault jobs (tr_*), also removes local job records and managed transcript result objects. Idempotent: returns success if already deleted.", "operationId": "deleteTranscription", "responses": { "200": { "description": "Delete operation processed (including idempotent success)" }, "400": { "description": "Missing transcription ID" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to voice/transcription service" }, "404": { "description": "Transcription not found or access denied" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Transcription ID (managed tr_* or direct provider ID)" } ], "x-permissions": [ "voice", "transcription" ] } }, "/voice/v1/speak": { "post": { "tags": [ "Voice" ], "summary": "Text-to-speech synthesis", "description": "Convert text to natural-sounding audio using ElevenLabs voices. Ideal for creating audio summaries of legal documents, client presentations, or accessibility features. Supports multiple languages and voice customization.", "operationId": "synthesizeSpeech", "responses": { "200": { "description": "Audio file generated successfully", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary" } }, "audio/wav": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Type": { "description": "Audio MIME type", "schema": { "type": "string", "example": "audio/mpeg" } }, "Content-Length": { "description": "Audio file size in bytes", "schema": { "type": "string" } } } }, "400": { "description": "Invalid request - missing or invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "text is required" } } } } } }, "401": { "description": "Authentication failed - invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 401 }, "message": { "type": "string", "example": "Invalid API key" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "AUTH_INVALID" } } } } } } } }, "403": { "description": "Permission denied - API key lacks voice/TTS access", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 403 }, "message": { "type": "string", "example": "API key does not have access to voice/TTS service" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "PERMISSION_DENIED" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Text to convert to speech", "maxLength": 5000 }, "voice_id": { "type": "string", "description": "ElevenLabs voice ID (defaults to Rachel - professional, clear)", "default": "EXAVITQu4vr4xnSDxMaL" }, "model_id": { "type": "string", "description": "ElevenLabs model ID", "default": "eleven_multilingual_v2", "enum": [ "eleven_multilingual_v2", "eleven_turbo_v2", "eleven_monolingual_v1" ] }, "output_format": { "type": "string", "description": "Audio output format", "default": "mp3_44100_128", "enum": [ "mp3_44100_128", "mp3_44100_192", "pcm_16000", "pcm_22050", "pcm_24000", "pcm_44100" ] }, "voice_settings": { "type": "object", "description": "Voice customization settings", "properties": { "stability": { "type": "number", "minimum": 0, "maximum": 1, "description": "Voice stability (0-1)" }, "similarity_boost": { "type": "number", "minimum": 0, "maximum": 1, "description": "Similarity boost (0-1)" }, "style": { "type": "number", "minimum": 0, "maximum": 1, "description": "Style exaggeration (0-1)" }, "use_speaker_boost": { "type": "boolean", "description": "Enable speaker boost" } } }, "language_code": { "type": "string", "description": "Language code for multilingual models", "example": "en" }, "optimize_streaming_latency": { "type": "integer", "description": "Optimize for streaming latency (0-4)", "minimum": 0, "maximum": 4 }, "enable_logging": { "type": "boolean", "description": "Enable request logging", "default": true }, "seed": { "type": "integer", "description": "Seed for reproducible generation" }, "previous_text": { "type": "string", "description": "Previous context for better pronunciation" }, "next_text": { "type": "string", "description": "Next context for better pronunciation" }, "apply_text_normalization": { "type": "boolean", "description": "Apply automatic text normalization", "default": true } } } } } }, "x-permissions": [ "voice", "tts" ] } }, "/voice/v1/speak/stream": { "post": { "tags": [ "Voice" ], "summary": "Stream text-to-speech audio", "description": "Convert text to speech using ElevenLabs AI voices with streaming for real-time playback. Returns audio data as an MP3 stream for immediate playback with minimal latency. Perfect for legal document narration, client presentations, or accessibility features.", "operationId": "streamTextToSpeech", "responses": { "200": { "description": "Audio stream successfully generated", "content": { "audio/mpeg": { "schema": { "type": "string", "format": "binary", "description": "MP3 audio stream" } } }, "headers": { "Content-Type": { "description": "Audio MIME type", "schema": { "type": "string", "example": "audio/mpeg" } }, "Transfer-Encoding": { "description": "Chunked encoding for streaming", "schema": { "type": "string", "example": "chunked" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "text is required" } } } } } }, "401": { "description": "Authentication failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Invalid API key" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "AUTH_INVALID" } } } } } } } }, "403": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "API key does not have access to voice/TTS service" }, "data": { "type": "object", "properties": { "code": { "type": "string", "example": "PERMISSION_DENIED" } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Text to convert to speech", "maxLength": 5000 }, "voice_id": { "type": "string", "description": "ElevenLabs voice ID (defaults to Rachel for professional clarity)", "default": "EXAVITQu4vr4xnSDxMaL" }, "model_id": { "type": "string", "description": "TTS model to use", "default": "eleven_multilingual_v2", "enum": [ "eleven_monolingual_v1", "eleven_multilingual_v1", "eleven_multilingual_v2", "eleven_turbo_v2" ] }, "voice_settings": { "type": "object", "description": "Optional voice tuning controls for delivery, consistency, and emphasis", "properties": { "stability": { "type": "number", "minimum": 0, "maximum": 1, "description": "Voice stability (0-1)" }, "similarity_boost": { "type": "number", "minimum": 0, "maximum": 1, "description": "Similarity boost (0-1)" }, "style": { "type": "number", "minimum": 0, "maximum": 1, "description": "Style exaggeration (0-1)" }, "use_speaker_boost": { "type": "boolean", "description": "Enable speaker boost" } } }, "language_code": { "type": "string", "description": "Language code (e.g., 'en', 'es', 'fr')" }, "output_format": { "type": "string", "description": "Audio output format", "enum": [ "mp3_44100_128", "mp3_22050_32", "pcm_16000", "pcm_22050", "pcm_24000", "pcm_44100" ], "default": "mp3_44100_128" }, "optimize_streaming_latency": { "type": "integer", "description": "Optimize for streaming latency (0-4)", "minimum": 0, "maximum": 4 }, "seed": { "type": "integer", "description": "Random seed for reproducible generation" }, "previous_text": { "type": "string", "description": "Previous text for context" }, "next_text": { "type": "string", "description": "Next text for context" }, "apply_text_normalization": { "type": "boolean", "description": "Apply text normalization", "default": true }, "enable_logging": { "type": "boolean", "description": "Enable request logging", "default": true } } } } } }, "x-permissions": [ "voice", "tts" ] } }, "/voice/v1/voices": { "get": { "tags": [ "Voice" ], "summary": "List available voices", "description": "Retrieve a list of available voices for text-to-speech synthesis. This endpoint provides access to a comprehensive catalog of voices with various characteristics, languages, and styles suitable for legal document narration, client presentations, and accessibility purposes.", "operationId": "listVoices", "responses": { "200": { "description": "List of available voices retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "voices": { "type": "array", "items": { "type": "object", "properties": { "voice_id": { "type": "string", "description": "Unique voice identifier" }, "name": { "type": "string", "description": "Voice name" }, "description": { "type": "string", "description": "Voice description" }, "category": { "type": "string", "description": "Voice category" }, "labels": { "type": "object", "description": "Voice characteristics and metadata" }, "preview_url": { "type": "string", "description": "URL to preview audio sample" }, "available_for_tiers": { "type": "array", "items": { "type": "string" }, "description": "Available subscription tiers" } } } }, "next_page_token": { "type": "string", "description": "Token for next page of results" }, "total_count": { "type": "integer", "description": "Total number of voices (if requested)" } } }, "example": { "voices": [ { "voice_id": "21m00Tcm4TlvDq8ikWAM", "name": "Rachel", "description": "A clear, professional voice perfect for legal presentations", "category": "premade", "labels": { "accent": "american", "age": "young", "gender": "female", "use_case": "narration" }, "preview_url": "https://api.elevenlabs.io/v1/voices/21m00Tcm4TlvDq8ikWAM/preview", "available_for_tiers": [ "free", "starter", "creator", "pro" ] } ], "next_page_token": "eyJ2b2ljZV9pZCI6IjIxbTAwVGNtNFRsdkRxOGlrV0FNIn0", "total_count": 142 } } } }, "400": { "description": "Invalid request parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to voice service" } }, "parameters": [ { "name": "page_size", "in": "query", "description": "Number of voices to return per page (max 100)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "next_page_token", "in": "query", "description": "Token for retrieving the next page of results", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search term to filter voices by name or description", "required": false, "schema": { "type": "string" } }, { "name": "voice_type", "in": "query", "description": "Filter by voice type", "required": false, "schema": { "type": "string", "enum": [ "premade", "cloned", "professional" ] } }, { "name": "category", "in": "query", "description": "Filter by voice category", "required": false, "schema": { "type": "string" } }, { "name": "collection_id", "in": "query", "description": "Filter by voice collection ID", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "enum": [ "name", "created_at", "updated_at" ] } }, { "name": "sort_direction", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "include_total_count", "in": "query", "description": "Whether to include total count in response", "required": false, "schema": { "type": "boolean", "default": false } } ], "x-permissions": [ "voice", "tts" ] } }, "/webhooks/v1/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook deliveries", "description": "Returns delivery attempts for the organization, newest first. Filter by endpoint_id or status to narrow results.", "operationId": "listWebhookDeliveries", "responses": { "200": { "description": "Deliveries list" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to webhooks service" } }, "parameters": [ { "name": "endpoint_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "delivered", "failed" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-permissions": [ "webhooks:read" ] } }, "/webhooks/v1/deliveries/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook delivery", "operationId": "getWebhookDelivery", "responses": { "200": { "description": "Delivery detail" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to webhooks service" }, "404": { "description": "Delivery not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "webhooks:read" ] } }, "/webhooks/v1/deliveries/{id}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Replay a webhook delivery", "description": "Re-sends the original event to its endpoint. The payload is reconstructed from the delivery record (same eventId, eventType, and occurred_at). Replay deliveries include a Case.dev replay marker header so receivers can distinguish replays from first-time deliveries. Uses the endpoint's current signing secret — not the one in force at the original delivery time.", "operationId": "replayWebhookDelivery", "responses": { "200": { "description": "Replay kicked off; inspect deliveries list to see the new attempt" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key lacks write access" }, "404": { "description": "Delivery or endpoint not found" }, "409": { "description": "Endpoint is no longer active" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "description": "Override payload to deliver. Must only be supplied when the delivery record lacks enough context to reconstruct the original event (rare). Defaults to an empty data envelope." } } } } } }, "x-permissions": [ "webhooks:write" ] } }, "/webhooks/v1/endpoints": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "description": "Returns the organization's webhook endpoints, newest first. Signing secrets are never included.", "operationId": "listWebhookEndpoints", "responses": { "200": { "description": "Webhook endpoints list" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to webhooks service" } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled", "auto_disabled" ] }, "description": "Filter by endpoint status" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "x-permissions": [ "webhooks:read" ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook endpoint", "description": "Creates a webhook endpoint that receives platform events matching the supplied event-type filters. Returns the generated signing secret ONCE — the response is the only time it is shown in plaintext.", "operationId": "createWebhookEndpoint", "responses": { "201": { "description": "Webhook endpoint created successfully. Persist the signing secret securely; it is shown only once.", "content": { "application/json": { "schema": { "type": "object", "required": [ "endpoint", "signingSecret" ], "properties": { "signingSecret": { "type": "string", "description": "One-time webhook signing secret." }, "endpoint": { "type": "object", "required": [ "id", "url", "description", "eventTypeFilters", "resourceScopes", "status", "disabledReason", "consecutiveFailureCount", "lastSuccessAt", "lastFailureAt", "hasPreviousSigningSecret", "previousSigningSecretExpiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string", "nullable": true }, "eventTypeFilters": { "type": "array", "items": { "type": "string" } }, "resourceScopes": { "type": "object", "nullable": true, "properties": { "vaultIds": { "type": "array", "items": { "type": "string" } }, "matterIds": { "type": "array", "items": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "active", "disabled", "auto_disabled" ] }, "disabledReason": { "type": "string", "nullable": true }, "consecutiveFailureCount": { "type": "integer" }, "lastSuccessAt": { "type": "string", "format": "date-time", "nullable": true }, "lastFailureAt": { "type": "string", "format": "date-time", "nullable": true }, "hasPreviousSigningSecret": { "type": "boolean" }, "previousSigningSecretExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "description": "Request body is invalid" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key lacks webhooks:write or the required service scopes" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "eventTypeFilters" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS callback URL that will receive event deliveries" }, "description": { "type": "string", "description": "Human-readable label for this endpoint" }, "eventTypeFilters": { "type": "array", "items": { "type": "string" }, "description": "Glob patterns of event types to deliver (e.g. \"vault.*\", \"ocr.job.completed\", \"*\")" }, "resourceScopes": { "type": "object", "description": "Optional per-resource allowlists. If vaultIds is set, only events for those vaults are delivered. Same for matterIds.", "properties": { "vaultIds": { "type": "array", "items": { "type": "string" } }, "matterIds": { "type": "array", "items": { "type": "string" } } } } } } } } }, "x-permissions": [ "webhooks:write" ] } }, "/webhooks/v1/endpoints/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook endpoint", "operationId": "getWebhookEndpoint", "responses": { "200": { "description": "Webhook endpoint" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to webhooks service" }, "404": { "description": "Endpoint not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "webhooks:read" ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook endpoint", "description": "Partially updates a webhook endpoint. Any omitted field is left unchanged. Signing secrets are rotated via the separate /rotate_secret endpoint.", "operationId": "updateWebhookEndpoint", "responses": { "200": { "description": "Updated endpoint" }, "400": { "description": "Invalid body" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key lacks write access" }, "404": { "description": "Endpoint not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string", "nullable": true }, "eventTypeFilters": { "type": "array", "items": { "type": "string" } }, "resourceScopes": { "type": "object", "nullable": true, "properties": { "vaultIds": { "type": "array", "items": { "type": "string" } }, "matterIds": { "type": "array", "items": { "type": "string" } } } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } } } } }, "x-permissions": [ "webhooks:write" ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook endpoint", "description": "Soft-deletes a webhook endpoint. Delivery stops immediately and the endpoint no longer appears in list results. Delivery history is preserved (and can be fetched via GET /deliveries with the endpoint_id filter) so audit trails and post-mortem debugging remain possible.", "operationId": "deleteWebhookEndpoint", "responses": { "204": { "description": "Endpoint deleted" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key lacks write access" }, "404": { "description": "Endpoint not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-permissions": [ "webhooks:write" ] } }, "/webhooks/v1/endpoints/{id}/rotate_secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate webhook signing secret", "description": "Generates a new signing secret for the endpoint. The previous secret remains valid until `previousSecretExpiresInSec` elapses (default 24h, max 30 days). During the grace window deliveries are signed with both secrets so receivers can migrate without downtime. Returns the new secret — this is the only time it is shown in plaintext.", "operationId": "rotateWebhookEndpointSecret", "responses": { "200": { "description": "Secret rotated" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key lacks write access" }, "404": { "description": "Endpoint not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "previousSecretExpiresInSec": { "type": "integer", "minimum": 0, "maximum": 2592000, "description": "How long (seconds) the old secret continues to be accepted. 0 invalidates immediately. Default: 86400 (24h)." } } } } } }, "x-permissions": [ "webhooks:write" ] } }, "/webhooks/v1/endpoints/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event to a webhook endpoint", "description": "Synchronously delivers a synthetic `webhook.test` event to the endpoint and returns the HTTP result. No retries. Useful for validating that a new endpoint is reachable and its signature verifier works. The delivery is not persisted in the delivery history.", "operationId": "testWebhookEndpoint", "responses": { "200": { "description": "Delivery result" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key lacks write access" }, "404": { "description": "Endpoint not found" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Event type to simulate. Defaults to \"webhook.test\"." }, "payload": { "type": "object", "description": "Custom `data` payload. Defaults to a small placeholder." } } } } } }, "x-permissions": [ "webhooks:write" ] } }, "/webhooks/v1/event_types": { "get": { "tags": [ "Webhooks" ], "summary": "List subscribable event types", "description": "Returns the catalog of event types that can be subscribed to via webhook endpoints. Each entry lists the required service scope the API key must carry to subscribe, plus the stability level.", "operationId": "listWebhookEventTypes", "responses": { "200": { "description": "Event type catalog" }, "401": { "description": "Invalid API key" }, "403": { "description": "API key does not have access to webhooks service" } }, "x-permissions": [ "webhooks:read" ] } } } }