Generations API – POST /api/generate-code-comments

This endpoint generates inline comments and DocBlocks for your source code, injecting annotations for classes, functions, and parameters without altering existing logic.

Authentication

All generation endpoints require a valid API token. Include your Bearer token in the Authorization header. Unauthenticated requests receive a 401 Unauthorized.

Endpoint

Method: POST

URL: https://app.docuwriter.ai/api/generate-code-comments

Headers

Key Value Required
Authorization Bearer `` Yes
Content-Type application/json Yes

Request Body

Body Type: JSON

Field Type Required Description
source_code string Yes Raw source code to comment
filename string Yes Name of the file, including extension
name string No Override for output filename (max 255 chars) 
{
  "source_code": "<?php\nfunction sum($a, $b) { return $a + $b; }",
  "filename": "sum.php"
}

Response

Success (200)

Returns the commented code and the suggested output filename.

{
  "success": true,
  "data": {
    "generation": "/**\n * Calculate the sum of two numbers.\n *\n * @param int $a First number\n * @param int $b Second number\n * @return int Sum of $a and $b\n */\nfunction sum($a, $b) { return $a + $b; }",
    "filename": "commented-sum.php"
  }
}

Error Cases

HTTP Status Code Path JSON Error Body
400 Bad Request Code too large for model limits { "success": false, "message": "The provided code is too large for processing. Please reduce the amount of code and try again." }
401 Unauthorized Missing/invalid token { "message": "Unauthenticated." }
403 Forbidden Out of credits { "success": false, "message": "You have no remaining credits. Please upgrade your plan." }
422 Unprocessable Entity Validation failures { "message": "The given data was invalid.", "errors": { "source_code": [...], "filename": [...] } }
500 Internal Server Error AI service or JSON parsing errors { "success": false, "message": "Error generating comments. Please try again." }

Interactive API Block

{
    "title": "Generate Code Comments",
    "description": "Inject inline comments and language-appropriate DocBlocks into your source code.",
    "method": "POST",
    "baseUrl": "https://app.docuwriter.ai",
    "endpoint": "/api/generate-code-comments",
    "headers": [
        {
            "key": "Authorization",
            "value": "Bearer <token>",
            "required": true
        },
        {
            "key": "Content-Type",
            "value": "application/json",
            "required": true
        }
    ],
    "queryParams": [],
    "pathParams": [],
    "bodyType": "json",
    "requestBody": "{\n  \"source_code\": \"<?php\\nfunction sum($a, $b) { return $a + $b; }\",\n  \"filename\": \"sum.php\"\n}",
    "formData": [],
    "rawBody": "",
    "responses": {
        "200": {
            "description": "Comments generated successfully",
            "body": "{\n  \"success\": true,\n  \"data\": {\n    \"generation\": \"...commented code...\",\n    \"filename\": \"commented-sum.php\"\n  }\n}"
        },
        "400": {
            "description": "Code too large for processing",
            "body": "{ \"success\": false, \"message\": \"The provided code is too large for processing...\" }"
        },
        "401": {
            "description": "Unauthorized",
            "body": "{ \"message\": \"Unauthenticated.\" }"
        },
        "403": {
            "description": "Out of credits",
            "body": "{ \"success\": false, \"message\": \"You have no remaining credits...\" }"
        },
        "422": {
            "description": "Validation error",
            "body": "{ \"message\": \"The given data was invalid.\", \"errors\": { ... } }"
        },
        "500": {
            "description": "Server or AI service error",
            "body": "{ \"success\": false, \"message\": \"Error generating comments. Please try again.\" }"
        }
    }
}