Documentation

Custom REST API

Integrate any REST API endpoint with ModelRed

🔗

Custom REST Endpoints

Connect any REST API endpoint to ModelRed with flexible authentication and request/response formats. Perfect for custom deployments and proprietary models.

Quick Setup

Get Started in 3 Steps

Connect any REST API endpoint for security testing.

1

Prepare Your Endpoint

Ensure your REST API endpoint is accessible and supports text generation.

https://your-api.example.com/v1/chat/completions
2

Choose Authentication

Configure authentication method (Bearer token, API key, or custom headers).

Bearer Token: Authorization: Bearer your-tokenAPI Key: X-API-Key: your-api-keyCustom: Custom-Auth: your-auth-value
3

Register Your Endpoint

PYTHON
from modelred import ModelRed

async with ModelRed() as client:
    await client.register_custom_rest_model(
        model_id="my-custom-api",
        endpoint_url="https://your-api.example.com/v1/chat/completions",
        auth_type="bearer",
        auth_value="your-bearer-token",
        request_format="openai_compatible"
    )

Authentication Types

🔑

Bearer Token

Standard OAuth 2.0 bearer token authentication

auth_type="bearer"
🎫

API Key

Simple API key in X-API-Key header

auth_type="api_key"
🔧

Custom Header

Custom authentication header

auth_type="custom_header"
🚫

No Authentication

Public endpoints without authentication

auth_type="none"

Request Formats

Supported Formats

Choose the request format that matches your API endpoint.

🤖

OpenAI Compatible

PYTHON
await client.register_custom_rest_model(
    model_id="openai-compatible",
    endpoint_url="https://api.example.com/v1/chat/completions",
    request_format="openai_compatible",
    response_path="choices.0.message.content"
)
⚡

Simple Format

PYTHON
await client.register_custom_rest_model(
    model_id="simple-api",
    endpoint_url="https://api.example.com/generate",
    request_format="simple",
    response_path="response"
)

Configuration Examples

OpenAI-Compatible API

PYTHON
# For APIs that follow OpenAI's chat completions format
await client.register_custom_rest_model(
    model_id="local-llama",
    endpoint_url="http://localhost:8000/v1/chat/completions",
    auth_type="bearer",
    auth_value="your-token",
    request_format="openai_compatible",
    response_path="choices.0.message.content",
    headers={
        "Content-Type": "application/json",
        "User-Agent": "ModelRed/1.0"
    }
)

Custom API with Custom Payload

PYTHON
# For APIs with custom request/response formats
await client.register_custom_rest_model(
    model_id="proprietary-model",
    endpoint_url="https://api.yourcompany.com/ai/generate",
    auth_type="custom_header",
    auth_value="secret-key-123",
    custom_header_name="X-Company-Auth",
    request_format="custom",
    response_path="data.generated_text",
    custom_payload_template={
        "input": "{prompt}",
        "parameters": {
            "max_tokens": 150,
            "temperature": 0.7
        }
    }
)

Public API without Authentication

PYTHON
# For public APIs that don't require authentication
await client.register_custom_rest_model(
    model_id="public-model",
    endpoint_url="https://api.public-ai.com/generate",
    auth_type="none",
    request_format="simple",
    response_path="text"
)

Common Issues

⚠️ Troubleshooting

Connection Failed
ConnectionError: Unable to connect to endpoint
Solutions:
  • • Verify endpoint URL is correct and accessible
  • • Check network connectivity and firewall settings
  • • Ensure API server is running and responding
Authentication Failed
AuthenticationError: 401 Unauthorized
Solutions:
  • • Verify auth_type matches your API's requirements
  • • Check that auth_value is correct and not expired
  • • Ensure custom_header_name is spelled correctly
Response Parsing Failed
ValueError: Cannot parse response at path 'data.text'
Solutions:
  • • Check response_path matches your API's response structure
  • • Test API response manually to verify JSON structure
  • • Ensure API returns valid JSON format

Quick Test

✅ Verify Your Setup

Run this test to confirm your custom REST API integration is working:

PYTHON
import asyncio
from modelred import ModelRed

async def test_custom_api():
    async with ModelRed() as client:
        # Register custom REST API
        await client.register_custom_rest_model(
            model_id="test-custom-api",
            endpoint_url="https://your-api.example.com/generate",
            auth_type="bearer",  # adjust based on your API
            auth_value="your-token"
        )
        print("✅ Custom REST API registered!")

        # Run security test
        result = await client.run_assessment(
            model_id="test-custom-api",
            test_suites=["basic_security"]
        )
        print(f"🔍 Assessment started: {result.assessment_id}")

asyncio.run(test_custom_api())

Use Cases

🎯 When to Use Custom REST

Perfect For

•

Self-hosted AI models

•

Proprietary AI services

•

Local development environments

•

Custom AI inference servers

Common Scenarios

•

Testing models not on major platforms

•

On-premise AI deployments

•

Custom fine-tuned models

•

Internal AI services

Next Steps

🧪

Run Security Tests

Start testing your custom API endpoints

🔗

Provider Overview

Compare all available providers