openapi: 3.0.3 info: title: TurfAI DMS API description: Document Management System API for TurfAI platform version: 0.9.0 contact: name: TurfAI Support servers: - url: http://localhost:1337/api description: Development server - url: https://api.turfai.com/api description: Production server components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token obtained from /auth/local endpoint schemas: Document: type: object properties: id: type: integer example: 123 attributes: type: object properties: title: type: string example: "Invoice Jan 2025" description: type: string example: "Monthly invoice" file_url: type: string format: uri example: "https://storage.googleapis.com/bucket/path/file.pdf" mime_type: type: string example: "application/pdf" file_size: type: integer example: 245678 tags: type: array items: type: string example: ["invoice", "2025"] createdAt: type: string format: date-time updatedAt: type: string format: date-time Collection: type: object properties: id: type: integer attributes: type: object properties: name: type: string example: "Invoices 2025" description: type: string documents: type: object properties: data: type: array items: $ref: '#/components/schemas/Document' Prompt: type: object properties: id: type: integer attributes: type: object properties: title: type: string example: "Invoice Extraction" type: type: string enum: [extraction, classification, summarization] level: type: string enum: [system, user] section: type: string example: "invoice" roles: type: array items: type: object properties: role: type: string enum: [system, user] prompt: type: string tasks: type: array items: type: string instructions: type: array items: type: string Activity: type: object properties: id: type: integer attributes: type: object properties: name: type: string example: "Invoice Processing Workflow" description: type: string status: type: string enum: [draft, active, paused, archived] workflow_definition: type: object properties: nodes: type: array items: type: object edges: type: array items: type: object WorkflowExecution: type: object properties: id: type: integer attributes: type: object properties: activity: type: object status: type: string enum: [queued, running, awaiting_user_input, completed, failed, cancelled] inputs: type: object outputs: type: object task_states: type: object error: type: string nullable: true createdAt: type: string format: date-time completedAt: type: string format: date-time nullable: true Error: type: object properties: error: type: object properties: status: type: integer name: type: string message: type: string details: type: object security: - BearerAuth: [] paths: /auth/local: post: tags: - Authentication summary: Login description: Authenticate user and get JWT token security: [] requestBody: required: true content: application/json: schema: type: object required: - identifier - password properties: identifier: type: string example: "user@example.com" password: type: string example: "password123" responses: '200': description: Login successful content: application/json: schema: type: object properties: jwt: type: string example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." user: type: object properties: id: type: integer username: type: string email: type: string '400': description: Invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' /documents/upload: post: tags: - Documents summary: Upload Document description: Upload a file and create document record requestBody: required: true content: multipart/form-data: schema: type: object required: - file - title properties: file: type: string format: binary title: type: string description: type: string tags: type: string description: JSON array as string example: '["invoice","2025"]' responses: '200': description: Document uploaded successfully content: application/json: schema: type: object properties: id: type: integer title: type: string file_url: type: string fileUrl: type: string mime_type: type: string file_size: type: integer '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' /documents: get: tags: - Documents summary: List Documents description: Get list of all documents with pagination parameters: - name: populate in: query schema: type: string example: "*" - name: pagination[page] in: query schema: type: integer example: 1 - name: pagination[pageSize] in: query schema: type: integer example: 25 - name: sort in: query schema: type: string example: "createdAt:desc" - name: filters[title][$contains] in: query schema: type: string responses: '200': description: List of documents content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Document' meta: type: object properties: pagination: type: object /documents/{id}: get: tags: - Documents summary: Get Single Document parameters: - name: id in: path required: true schema: type: integer - name: populate in: query schema: type: string example: "*" responses: '200': description: Document details content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Document' '404': description: Document not found delete: tags: - Documents summary: Delete Document parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Document deleted '404': description: Document not found /documents/{id}/metadata: put: tags: - Documents summary: Update Document Metadata parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: title: type: string description: type: string tags: type: array items: type: string responses: '200': description: Metadata updated /collections: get: tags: - Collections summary: List Collections parameters: - name: populate in: query schema: type: string example: "*" responses: '200': description: List of collections content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Collection' /collections/create-collection: post: tags: - Collections summary: Create Collection requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string description: type: string responses: '201': description: Collection created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Collection' /collections/{id}/documents: get: tags: - Collections summary: Get Collection Documents parameters: - name: id in: path required: true schema: type: integer responses: '200': description: List of documents in collection /collections/{id}/add-document: post: tags: - Collections summary: Add Document to Collection parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object required: - documentId properties: documentId: type: integer responses: '200': description: Document added to collection /collections/{id}/remove-document: post: tags: - Collections summary: Remove Document from Collection parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object required: - documentId properties: documentId: type: integer responses: '200': description: Document removed from collection /collections/{id}/delete: delete: tags: - Collections summary: Delete Collection parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Collection deleted /prompts: get: tags: - Prompts summary: List Prompts parameters: - name: populate in: query schema: type: string example: "*" - name: filters[level][$eq] in: query schema: type: string enum: [system, user] responses: '200': description: List of prompts content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Prompt' post: tags: - Prompts summary: Create Prompt requestBody: required: true content: application/json: schema: type: object properties: data: type: object required: - title - type - level properties: title: type: string type: type: string level: type: string section: type: string roles: type: array items: type: object tasks: type: array items: type: string instructions: type: array items: type: string responses: '201': description: Prompt created /prompts/{id}: get: tags: - Prompts summary: Get Single Prompt parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Prompt details content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Prompt' put: tags: - Prompts summary: Update Prompt parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: data: type: object responses: '200': description: Prompt updated delete: tags: - Prompts summary: Delete Prompt parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Prompt deleted /activities: get: tags: - Activities summary: List Activities (Workflows) parameters: - name: populate in: query schema: type: string example: "*" responses: '200': description: List of workflows content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Activity' post: tags: - Activities summary: Create Activity (Workflow) requestBody: required: true content: application/json: schema: type: object properties: data: type: object required: - name - workflow_definition properties: name: type: string description: type: string status: type: string workflow_definition: type: object responses: '201': description: Activity created /activities/{id}: get: tags: - Activities summary: Get Single Activity parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Activity details put: tags: - Activities summary: Update Activity parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object properties: data: type: object responses: '200': description: Activity updated delete: tags: - Activities summary: Delete Activity parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Activity deleted /workflow-executions: post: tags: - Workflow Executions summary: Create Workflow Execution requestBody: required: true content: application/json: schema: type: object properties: data: type: object required: - activity properties: activity: type: integer inputs: type: object responses: '201': description: Execution created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WorkflowExecution' /workflow-executions/{id}/execute: post: tags: - Workflow Executions summary: Execute Workflow parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object required: - document_url properties: document_url: type: string mime_type: type: string responses: '200': description: Workflow queued for execution content: application/json: schema: type: object properties: success: type: boolean message: type: string execution_id: type: integer job_id: type: string /workflow-executions/{id}/status: get: tags: - Workflow Executions summary: Get Execution Status description: Poll this endpoint to check workflow execution progress parameters: - name: id in: path required: true schema: type: integer responses: '200': description: Execution status content: application/json: schema: type: object properties: id: type: integer status: type: string enum: [queued, running, awaiting_user_input, completed, failed, cancelled] task_states: type: object outputs: type: object error: type: string nullable: true completedAt: type: string format: date-time nullable: true /workflow-executions/{id}/resume: post: tags: - Workflow Executions summary: Resume Paused Workflow description: Resume workflow when status is awaiting_user_input parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: type: object required: - correlation_token - user_data properties: correlation_token: type: string user_data: type: object responses: '200': description: Workflow resumed /dashboard/stats: get: tags: - Dashboard summary: Get Dashboard Statistics parameters: - name: period in: query schema: type: string enum: [24h, 7d, 30d] default: "7d" - name: tenant in: query schema: type: string responses: '200': description: Dashboard statistics content: application/json: schema: type: object properties: totalDocuments: type: integer totalDocumentsGrowth: type: number totalActivities: type: integer totalActivitiesGrowth: type: number totalPrompts: type: integer totalPromptsGrowth: type: number totalExecutions: type: integer totalExecutionsGrowth: type: number /dashboard/activity: get: tags: - Dashboard summary: Get Activity Chart Data parameters: - name: period in: query schema: type: string enum: [24h, 7d, 30d] - name: tenant in: query schema: type: string responses: '200': description: Activity data for charts /dashboard/recent-activity: get: tags: - Dashboard summary: Get Recent Activity Feed parameters: - name: limit in: query schema: type: integer default: 10 responses: '200': description: Recent activity items /dashboard/health: get: tags: - Dashboard summary: System Health Check security: [] responses: '200': description: System health status content: application/json: schema: type: object properties: database: type: string enum: [healthy, unhealthy] api: type: string enum: [healthy, unhealthy] processing: type: string enum: [healthy, unhealthy] storage: type: string enum: [healthy, unhealthy] overall: type: string enum: [healthy, degraded, unhealthy]