API Reference

The Cowriter extension exposes several AJAX endpoints under /typo3/ajax/cowriter/. All endpoints require an authenticated backend session.

Common response format

All endpoints return JSON with a success boolean. On error, an error string describes the problem.

Rate limit headers are included on every response:

X-RateLimit-Limit — maximum requests per window
X-RateLimit-Remaining — requests remaining in current window
Retry-After — seconds until reset (only on HTTP 429)

Completion endpoints

POST /cowriter/complete

Generate a completion from a prompt using the default or specified LLM configuration.

Request body:

{
    "prompt": "Write an introduction about TYPO3",
    "configuration": "openai-default"
}

Response (200):

{
    "success": true,
    "content": "TYPO3 is a powerful...",
    "model": "gpt-5.2",
    "finishReason": "stop",
    "wasTruncated": false,
    "wasFiltered": false,
    "usage": {
        "promptTokens": 50,
        "completionTokens": 120,
        "totalTokens": 170
    }
}

POST /cowriter/stream

Stream a completion via Server-Sent Events (SSE). Same request format as /cowriter/complete.

Returns text/event-stream with JSON chunks:

data: {"content": "TYPO3 ", "done": false}
data: {"content": "is a ", "done": false}
data: {"content": "powerful...", "done": true, "model": "gpt-5.2"}

POST /cowriter/task-execute

Execute a predefined task with context assembly.

Request body:

{
    "taskIdentifier": "improve-text",
    "instruction": "Improve this text",
    "context": "<p>Current editor content</p>",
    "contextScope": "content_element",
    "configuration": "openai-default",
    "referencePages": [
        {"pid": 42, "relation": "style guide"}
    ]
}

Translation

POST /cowriter/translate

Translate text to a target language.

Request body:

{
    "text": "Hello world",
    "targetLanguage": "de",
    "formality": "formal",
    "domain": "technical",
    "configuration": "claude-fast"
}

formality defaults to "default", domain defaults to "general". configuration is optional.

Response (200):

{
    "success": true,
    "translation": "Hallo Welt",
    "sourceLanguage": "en",
    "confidence": 0.95,
    "usage": {
        "promptTokens": 30,
        "completionTokens": 10,
        "totalTokens": 40
    }
}

Vision / Alt text

POST /cowriter/vision

Analyze an image and generate descriptive alt text.

Request body:

{
    "imageUrl": "https://example.com/photo.jpg",
    "prompt": "Generate a concise, descriptive alt text for this image."
}

The prompt defaults to a standard alt text generation prompt if omitted.

Response (200):

{
    "success": true,
    "altText": "A red bicycle parked against a brick wall",
    "model": "gpt-5.2",
    "confidence": 0.92,
    "usage": {
        "promptTokens": 200,
        "completionTokens": 15,
        "totalTokens": 215
    }
}

Templates

GET /cowriter/templates

List available prompt templates (tasks with category = 'content').

Response (200):

{
    "success": true,
    "templates": [
        {
            "identifier": "improve-text",
            "name": "Improve Text",
            "description": "Enhance readability and quality",
            "category": "content"
        }
    ]
}

Tool calling

POST /cowriter/tools

Execute an LLM request with tool calling capabilities.

Request body:

{
    "prompt": "Find all headings in the content",
    "tools": ["query_content"]
}

tools is an optional array of tool names to enable. If omitted, all available tools are enabled.

Response (200):

{
    "success": true,
    "content": "I found 3 headings...",
    "toolCalls": [],
    "finishReason": "stop",
    "usage": {
        "promptTokens": 100,
        "completionTokens": 50,
        "totalTokens": 150
    }
}

Configurations

GET /cowriter/configurations

List active LLM configurations available for selection.

Response (200):

{
    "success": true,
    "configurations": [
        {
            "identifier": "openai-default",
            "name": "OpenAI GPT-5.2",
            "isDefault": true
        }
    ]
}

Error responses

All endpoints use standard HTTP status codes:

400 — Invalid JSON, missing required fields, or fields exceeding maximum length (32 KB)
429 — Rate limit exceeded (includes Retry-After header)
500 — LLM service error

{
    "success": false,
    "error": "Missing or empty text parameter."
}