diff --git a/trustgraph-base/tests/README.md b/trustgraph-base/tests/README.md
new file mode 100644
index 00000000..7b12c3a4
--- /dev/null
+++ b/trustgraph-base/tests/README.md
@@ -0,0 +1,238 @@
+# TrustGraph Python API Integration Tests
+
+This directory contains integration tests for the TrustGraph Python API refactor.
+
+## Overview
+
+The integration tests verify the following components:
+- **Basic API instantiation** and client creation
+- **REST API** functionality (synchronous and asynchronous)
+- **WebSocket API** functionality (synchronous and asynchronous)
+- **Bulk operations** for data import/export
+- **Metrics** endpoints
+- **Streaming types** and data structures
+
+## Prerequisites
+
+1. **Python dependencies:**
+   ```bash
+   pip install pytest pytest-asyncio
+   ```
+
+2. **Running TrustGraph Gateway API:**
+   - The tests require a running TrustGraph Gateway API server
+   - Default URL: `http://localhost:8088/`
+   - Configure via environment variables (see below)
+
+## Running the Tests
+
+### Quick Start (No Gateway Required)
+
+To run tests in "skip mode" (validates structure without requiring a running server):
+
+```bash
+export SKIP_INTEGRATION_TESTS=true
+pytest tests/test_api_integration.py -v
+```
+
+### Full Integration Tests (Requires Running Gateway)
+
+1. **Start your TrustGraph Gateway API server**
+
+2. **Configure environment variables:**
+   ```bash
+   export TRUSTGRAPH_URL=http://localhost:8088/
+   export TRUSTGRAPH_TOKEN=your-auth-token-here  # Optional
+   export TRUSTGRAPH_TEST_FLOW=test-flow         # Optional
+   export SKIP_INTEGRATION_TESTS=false           # Enable tests
+   ```
+
+3. **Run the tests:**
+   ```bash
+   pytest tests/test_api_integration.py -v
+   ```
+
+### Running Specific Test Classes
+
+```bash
+# Test only REST API
+pytest tests/test_api_integration.py::TestRESTAPI -v
+
+# Test only WebSocket API
+pytest tests/test_api_integration.py::TestWebSocketAPI -v
+
+# Test only async functionality
+pytest tests/test_api_integration.py::TestAsyncRESTAPI -v
+pytest tests/test_api_integration.py::TestAsyncWebSocketAPI -v
+
+# Test only bulk operations
+pytest tests/test_api_integration.py::TestBulkOperations -v
+
+# Test only metrics
+pytest tests/test_api_integration.py::TestMetrics -v
+```
+
+### Running with Coverage
+
+```bash
+pytest tests/test_api_integration.py --cov=trustgraph.api --cov-report=html
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TRUSTGRAPH_URL` | Gateway API URL | `http://localhost:8088/` |
+| `TRUSTGRAPH_TOKEN` | Authentication token | `None` |
+| `TRUSTGRAPH_TEST_FLOW` | Flow ID for testing | `test-flow` |
+| `SKIP_INTEGRATION_TESTS` | Skip tests requiring live server | `false` |
+
+## Test Categories
+
+### 1. Basic Connection Tests (`TestBasicConnection`)
+- API instantiation with/without token
+- Context manager support
+- Lazy initialization of clients
+
+### 2. REST API Tests (`TestRESTAPI`)
+- Flow listing
+- Flow class listing
+- Flow instance creation
+- Method existence verification
+
+### 3. Async REST API Tests (`TestAsyncRESTAPI`)
+- Async flow operations
+- Async context manager
+- Async/await patterns
+
+### 4. WebSocket API Tests (`TestWebSocketAPI`)
+- WebSocket client creation
+- Flow instance creation
+- Method availability
+- URL conversion (HTTP → WS)
+
+### 5. Async WebSocket API Tests (`TestAsyncWebSocketAPI`)
+- Async WebSocket operations
+- Streaming support verification
+- Method signatures
+
+### 6. Bulk Operations Tests (`TestBulkOperations`)
+- Bulk client instantiation
+- Import/export methods
+- Async bulk operations
+- Iterator-based data transfer
+
+### 7. Metrics Tests (`TestMetrics`)
+- Metrics endpoint access
+- Prometheus format validation
+- Async metrics retrieval
+
+### 8. Streaming Types Tests (`TestStreamingTypes`)
+- `AgentThought` chunk creation
+- `AgentObservation` chunk creation
+- `AgentAnswer` chunk creation
+- `RAGChunk` creation
+
+### 9. Triple Type Tests (`TestTripleType`)
+- Triple data structure validation
+
+## Test Structure
+
+```
+tests/
+├── __init__.py                  # Test package marker
+├── README.md                    # This file
+└── test_api_integration.py      # Main integration test suite
+```
+
+## Adding New Tests
+
+To add new integration tests:
+
+1. **Create a new test class** in `test_api_integration.py`:
+   ```python
+   class TestNewFeature:
+       """Test new feature functionality"""
+
+       @skip_if_no_gateway
+       def test_new_feature(self):
+           api = Api(url=GATEWAY_URL, token=AUTH_TOKEN)
+           # Your test code here
+           assert result is not None
+   ```
+
+2. **Add the `@skip_if_no_gateway` decorator** to tests requiring a live server
+
+3. **Use pytest.mark.asyncio** for async tests:
+   ```python
+   @skip_if_no_gateway
+   @pytest.mark.asyncio
+   async def test_async_feature(self):
+       api = Api(url=GATEWAY_URL, token=AUTH_TOKEN)
+       result = await api.async_flow().list()
+       assert isinstance(result, list)
+   ```
+
+## Continuous Integration
+
+For CI/CD pipelines:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Run Integration Tests
+  env:
+    TRUSTGRAPH_URL: http://localhost:8088/
+    SKIP_INTEGRATION_TESTS: false
+  run: |
+    # Start Gateway API in background
+    ./start-gateway.sh &
+    sleep 10
+
+    # Run tests
+    pytest tests/test_api_integration.py -v
+
+    # Stop Gateway API
+    ./stop-gateway.sh
+```
+
+## Troubleshooting
+
+### Tests are skipped
+- Check that `SKIP_INTEGRATION_TESTS` is set to `false`
+- Verify the Gateway API is running at the configured URL
+
+### Connection errors
+- Verify `TRUSTGRAPH_URL` is correct
+- Check that the Gateway API is accessible
+- Ensure firewall rules allow connections
+
+### Authentication errors
+- Verify `TRUSTGRAPH_TOKEN` is set correctly
+- Check token validity with the Gateway API
+
+### Timeout errors
+- Increase timeout in Api instantiation
+- Check Gateway API performance
+- Verify network connectivity
+
+## Future Enhancements
+
+Planned test additions:
+- End-to-end streaming tests (requires live LLM)
+- Bulk operation performance tests
+- Error handling and edge cases
+- WebSocket reconnection scenarios
+- Token refresh mechanisms
+- Multi-flow coordination tests
+
+## Contributing
+
+When adding new API features:
+1. Add corresponding integration tests
+2. Document environment variables if needed
+3. Update this README with new test categories
+4. Ensure tests can run in skip mode for CI
+
+## License
+
+Same as TrustGraph project license.