openapi: 3.0.3 info: title: Insforge Records API version: 2.0.0 description: PostgREST-style database record operations paths: /api/database/records/{tableName}: get: summary: Query Records description: Query records from a table with filtering, sorting, and pagination tags: - Client security: - bearerAuth: [] - apiKey: [] parameters: - name: tableName in: path required: true schema: type: string description: Name of the table to query example: users - name: limit in: query schema: type: integer default: 100 minimum: 1 maximum: 1000 description: Maximum number of records to return - name: offset in: query schema: type: integer default: 0 minimum: 0 description: Number of records to skip for pagination - name: order in: query schema: type: string description: Sort order (e.g., "createdAt.desc", "name.asc") example: createdAt.desc - name: select in: query schema: type: string description: Comma-separated list of columns to return example: id,name,email - name: field in: query schema: type: string description: Filter by field value (e.g., "?status=eq.active", "?age=gt.18") example: status=eq.active responses: '200': description: List of records headers: X-Total-Count: schema: type: integer description: Total number of records matching the query Content-Range: schema: type: string description: Range of records returned (e.g., "0-99/1234") content: application/json: schema: type: array items: type: object additionalProperties: true example: - id: 248373e1-0aea-45ce-8844-5ef259203749 name: John Doe email: john@example.com createdAt: '2025-07-18T05:37:24.338Z' updatedAt: '2025-07-18T05:37:24.338Z' - id: 348373e1-0aea-45ce-8844-5ef259203750 name: Jane Smith email: jane@example.com createdAt: '2025-07-19T08:15:10.123Z' updatedAt: '2025-07-19T08:15:10.123Z' '400': description: Invalid query parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: INVALID_QUERY message: Invalid filter syntax statusCode: 400 nextActions: Check PostgREST filter documentation '404': description: Table not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: TABLE_NOT_FOUND message: Table 'nonexistent' does not exist statusCode: 404 nextActions: Check table name and try again post: summary: Create Records description: Create one or more records. Request body MUST be an array. tags: - Client security: - bearerAuth: [] - apiKey: [] parameters: - name: tableName in: path required: true schema: type: string description: Name of the table example: users - name: Prefer in: header schema: type: string enum: - return=representation description: >- Include to return created records in response (otherwise returns empty array) requestBody: required: true content: application/json: schema: type: array items: type: object additionalProperties: true minItems: 1 example: - name: John Doe email: john@example.com age: 30 responses: '201': description: Records created content: application/json: schema: type: array items: type: object additionalProperties: true examples: without_prefer: summary: Response without Prefer header value: [] with_prefer: summary: 'Response with Prefer: return=representation' value: - id: 248373e1-0aea-45ce-8844-5ef259203749 name: John Doe email: john@example.com age: 30 createdAt: '2025-07-18T05:37:24.338Z' updatedAt: '2025-07-18T05:37:24.338Z' '400': description: Invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: VALIDATION_ERROR message: 'Invalid field type: expected integer for ''age''' statusCode: 400 nextActions: Ensure field types match the table schema '404': description: Table not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: TABLE_NOT_FOUND message: Table 'nonexistent' does not exist statusCode: 404 nextActions: Create the table first patch: summary: Update Records description: Update records matching query filters tags: - Client security: - bearerAuth: [] - apiKey: [] parameters: - name: tableName in: path required: true schema: type: string description: Name of the table example: users - name: id in: query schema: type: string description: >- Filter records by ID (e.g., "?id=eq.123e4567-e89b-12d3-a456-426614174000") example: eq.123e4567-e89b-12d3-a456-426614174000 - name: Prefer in: header schema: type: string enum: - return=representation description: Include to return updated records in response requestBody: required: true content: application/json: schema: type: object additionalProperties: true example: name: Jane Doe email: jane.doe@example.com responses: '200': description: Records updated content: application/json: schema: type: array items: type: object additionalProperties: true examples: without_prefer: summary: Response without Prefer header value: [] with_prefer: summary: 'Response with Prefer: return=representation' value: - id: 123e4567-e89b-12d3-a456-426614174000 name: Jane Doe email: jane.doe@example.com createdAt: '2025-01-01T00:00:00Z' updatedAt: '2025-01-21T11:00:00Z' '400': description: Invalid input content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: VALIDATION_ERROR message: Invalid field type statusCode: 400 nextActions: Check field types match table schema '404': description: No records found to update content: application/json: schema: type: array items: type: object example: [] delete: summary: Delete Records description: Delete records matching query filters tags: - Client security: - bearerAuth: [] - apiKey: [] parameters: - name: tableName in: path required: true schema: type: string description: Name of the table example: users - name: id in: query schema: type: string description: >- Filter records by ID (e.g., "?id=eq.123e4567-e89b-12d3-a456-426614174000") example: eq.123e4567-e89b-12d3-a456-426614174000 - name: Prefer in: header schema: type: string enum: - return=representation description: Include to return deleted records in response responses: '200': description: Records deleted (with Prefer header) content: application/json: schema: type: array items: type: object additionalProperties: true examples: records_deleted: summary: Records were deleted value: - id: 123e4567-e89b-12d3-a456-426614174000 name: Deleted User createdAt: '2025-01-01T00:00:00Z' updatedAt: '2025-01-21T11:00:00Z' no_records: summary: No records found to delete value: [] '204': description: Records deleted (without Prefer header) components: securitySchemes: bearerAuth: type: http scheme: bearer apiKey: type: apiKey in: header name: x-api-key schemas: ErrorResponse: type: object required: - error - message - statusCode properties: error: type: string description: Error code for programmatic handling example: VALIDATION_ERROR message: type: string description: Human-readable error message example: Invalid input data statusCode: type: integer description: HTTP status code example: 400 nextActions: type: string description: Suggested action to resolve the error example: Check the request body format Record: type: object properties: id: type: string format: uuid description: Auto-generated UUID createdAt: type: string format: date-time description: Timestamp when record was created updatedAt: type: string format: date-time description: Timestamp when record was last updated additionalProperties: true description: Base record structure with system fields security: - bearerAuth: [] - apiKey: []