insforge--insforge/examples/response-examples.md

InsForge API Response Format Examples

All API responses now follow a consistent format with success field and proper structure.

Success Response Format

{
  "success": true,
  "data": <response_data>,
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z",
    "pagination": { // optional, only for list endpoints
      "total": 100,
      "limit": 10,
      "offset": 0,
      "page": 1,
      "totalPages": 10
    }
  }
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {} // optional
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Endpoint Examples

Authentication Endpoints

POST /auth/register

Success Response (201):

{
  "success": true,
  "data": {
    "user": {
      "id": "123",
      "email": "user@example.com"
    },
    "token": "eyJhbGciOiJIUzI1NiIs..."
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Error Response (400):

{
  "success": false,
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "User already exists"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

POST /auth/login

Success Response (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "123",
      "name": "John Doe",
      "email": "user@example.com"
    },
    "token": "eyJhbGciOiJIUzI1NiIs..."
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Error Response (401):

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid credentials"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

GET /auth/me

Success Response (200):

{
  "success": true,
  "data": {
    "user": {
      "id": "123",
      "email": "user@example.com",
      "type": "user"
    }
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

GET /auth/users

Success Response (200):

{
  "success": true,
  "data": [
    {
      "id": "123",
      "email": "user1@example.com",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "124",
      "email": "user2@example.com",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Tables Endpoints

GET /database/tables

Success Response (200):

{
  "success": true,
  "data": ["posts", "comments"],
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

POST /database/tables

Success Response (201):

{
  "success": true,
  "data": {
    "message": "Table created successfully",
    "table_name": "posts"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

GET /database/records/:table

Success Response with Pagination (200):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "First Post",
      "content": "Hello World"
    },
    {
      "id": 2,
      "title": "Second Post",
      "content": "Another post"
    }
  ],
  "meta": {
    "pagination": {
      "total": 50,
      "limit": 10,
      "offset": 0,
      "page": 1,
      "totalPages": 5
    },
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

GET /database/records/:table?id=eq.:id

Success Response (200):

{
  "success": true,
  "data": {
    "id": 1,
    "title": "First Post",
    "content": "Hello World",
    "created_at": "2024-01-01T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Error Response (404):

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Record not found"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

POST /database/records/:table

Success Response (201):

{
  "success": true,
  "data": {
    "message": "Records inserted successfully",
    "inserted": 3,
    "ids": [1, 2, 3]
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

PATCH /database/records/:table?id=eq.:id

Success Response (200):

{
  "success": true,
  "data": {
    "message": "Record updated successfully",
    "affected": 1
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

DELETE /database/records/:table?id=eq.:id

Success Response (200):

{
  "success": true,
  "data": {
    "message": "Record deleted successfully",
    "affected": 1
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

GET /database/tables/:table/schema

Success Response (200):

{
  "success": true,
  "data": {
    "table_name": "posts",
    "columns": [
      {
        "name": "id",
        "type": "INTEGER",
        "nullable": false,
        "primary_key": true,
        "default_value": null
      },
      {
        "name": "title",
        "type": "TEXT",
        "nullable": false,
        "primary_key": false,
        "default_value": null
      }
    ]
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

PATCH /database/tables/:table

Success Response (200):

{
  "success": true,
  "data": {
    "message": "Table schema updated successfully",
    "table_name": "posts",
    "operations": [
      "Added column: tags",
      "Renamed column: content → body",
      "Dropped columns: temp_field"
    ]
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

DELETE /database/tables/:table

Success Response (200):

{
  "success": true,
  "data": {
    "message": "Table deleted successfully",
    "table_name": "posts"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Metadata Endpoints

GET /metadata

Success Response (200):

{
  "success": true,
  "data": {
    "app_name": "My InsForge App",
    "app_description": "Backend as a Service",
    "created_at": "2024-01-01T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

GET /metadata/api-key

Success Response (200):

{
  "success": true,
  "data": {
    "api_key": "ik_1234567890abcdef..."
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

MCP Endpoints

GET /mcp/metadata

Success Response (200):

{
  "success": true,
  "data": {
    "app_name": "My InsForge App",
    "app_description": "Backend as a Service",
    "mcp_tools": {
      "database": {
        "create_table": true,
        "modify_table": true,
        "delete_table": true,
        "query_records": true,
        "insert_records": true,
        "update_records": true,
        "delete_records": true
      }
    }
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

System Endpoints

GET /health

Success Response (200):

{
  "success": true,
  "data": {
    "status": "ok",
    "service": "Insforge Backend",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Common Error Codes

• MISSING_AUTH - No authentication provided
• INVALID_AUTH - Invalid authentication token or API key
• INVALID_CREDENTIALS - Wrong username/password
• TOKEN_EXPIRED - JWT token has expired
• FORBIDDEN - Access denied
• INSUFFICIENT_PERMISSIONS - Missing required permissions
• VALIDATION_ERROR - Input validation failed
• INVALID_INPUT - Invalid input format
• MISSING_FIELD - Required field missing
• NOT_FOUND - Resource not found
• ALREADY_EXISTS - Resource already exists
• DATABASE_ERROR - Database operation failed
• CONSTRAINT_VIOLATION - Database constraint violated
• INTERNAL_ERROR - Internal server error
• SERVICE_UNAVAILABLE - Service temporarily unavailable