Generate Content - WriterzRoom

POST /generate starts a new content generation job relative to the https://api.writerzroom.com/api base URL. It accepts the selected template, selected style profile, generation mode, optional vertical, and structured user input required for that request. The response returns a request_id rather than a completed draft because generation runs asynchronously.

Generation Overview

Template

Defines the content structure.

Style

Controls tone, voice, and audience fit.

Input

Supplies topic, audience, and requirements.

Request ID

Tracks the job until completion.

Request

POST https://api.writerzroom.com/api/generate
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "template_id": "blog_article_generator",
  "style_profile_id": "general_blog",
  "generation_mode": "standard",
  "user_input": {
    "topic": "The future of AI in content marketing",
    "target_audience": "Marketing directors at B2B SaaS companies",
    "objective": "Educate on practical AI adoption strategies",
    "key_points": ["ROI measurement", "Team workflows", "Tool selection"]
  },
  "vertical_id": "saas_tech"
}

Uploaded sources

For a template parameter with type: file_upload, upload the file first using authenticated POST /parse-file with multipart/form-data and a file field. Use the same authenticated account for upload and generation. The response contains a stored source_id, a short preview_text, extraction coverage, and context size information. Full extracted text and location offsets stay in the server-owned record. Pass the ID under that template parameter’s name. For example, a template with reference_files accepts this inside user_input or dynamic_parameters:

{
  "reference_files_f0_source_id": "SOURCE_ID_FROM_PARSE_FILE",
  "reference_files_f1_source_id": "ANOTHER_SOURCE_ID"
}

Use at most five files per parameter and ten per request. The backend resolves the template itself and checks source ownership, accepted formats, template size limits and stored coverage. Browser-supplied text or a claimed complete coverage status cannot satisfy a required source. A missing, partial, empty, unavailable, foreign or over-budget source produces a corrective 422 response before credits are charged. Storage failures return 503 without starting generation. All selected sources must fit one combined 60,000-character context budget, including labels. Oversized work needs a smaller relevant selection or separate requests; it is not silently truncated. OCR is not performed. Scanned pages and detected image content require a searchable text-only copy or a reviewed export. Old payloads containing only *_extracted_text must be uploaded again. Accepted requests return source_coverage; the generation metadata and content passport retain that coverage and the extracted source locations. This records ingestion, not factual verification or release approval.

Response

{
  "request_id": "req_xyz789",
  "status": "pending",
  "message": "Content generation started.",
  "links": {
    "status": "/api/generate/status/req_xyz789",
    "stream": "/api/generate/stream/req_xyz789"
  }
}

Core Request Fields

Field	Required	Description
`template_id`	Yes	Template identifier, such as `blog_article_generator`
`style_profile_id`	Yes	Style profile identifier, such as `general_blog`
`generation_mode`	Recommended	Generation tier, such as `quick`, `standard`, or `premium`
`user_input`	Yes	Structured inputs required by the selected template
`vertical_id`	Optional	Domain configuration, such as `saas_tech`, `medical_ai`, or `political`
`user_input.length_preset`	Optional	`brief`, `standard` or `comprehensive` (or a preset the template declares). Defaults to the template’s default length, usually `standard`
`user_input.word_range`	Optional	A custom range, `{"min": 900, "max": 1400}`, inside the template’s limits
`user_input.word_count_target`	Optional	Older single-number form, read as that figure to 15% above it

The template’s lengths, and which tiers can deliver each, are on Get Template by Slug.

Core Request Pattern

Choose a template identifier

Select the content structure that matches the output you want to create.

Choose a style profile identifier

Select the writing behavior that controls tone, voice, depth, and audience fit.

Provide required input fields

Add the required fields inside the user_input object.

Submit the request

Call POST /generate and store the returned request_id.

Poll until complete

Poll /generate/status/{request_id} until the request returns completed or failed.

Best Practice

An HTTP 422 response at submission is an admission rejection, before a workflow or draft is created and before generation credits are charged. Inspect the returned validation or admission reason and correct the indicated input before resubmitting. Structured field errors can identify the location and rule that failed. Some templates declare which of their options can be combined. For those templates a 422 also covers a combination that cannot describe one artifact, such as a graduate course with nine learner hours, and an unknown value for a fixed-choice option or a missing required one. The detail lists every reason. A template option set to auto is resolved to a concrete value at admission, and the run uses that value. Length refusals return detail as an object with a code and a readable message:

`code`	Meaning
`tier_too_low_for_length`	The tier cannot write this length in its time budget. `required_tier` names one that can; resubmit on it, or ask for a shorter length
`tier_not_available`	The tier is ruled out for this workflow or context whatever the length, for example disabled by the template. `available_tiers` lists the tiers that can run it
`length_out_of_range`	The range exceeds the template’s maximum; `bounds` gives its limits
`length_not_deliverable`	No tier can write this length in its time budget; choose a shorter length
`unknown_length_preset`	The preset is not one this template offers; `presets` lists them
`invalid_word_range`	The range is not two whole numbers with min no greater than max

After a request is accepted, retain its request_id and poll its execution status. A later failure is a different lifecycle event and follows the failed-generation refund path. Do not infer the actual writer model solely from the run-level default; complexity and stage authorization can select a different prose route. Validate template and style identifiers before submitting large batches of requests. That reduces avoidable failures and makes automation more reliable.

Use /templates and /style-profiles to fetch valid identifiers programmatically rather than hardcoding them.

Check Generation Status

Poll the request until content completes or fails.

Endpoints Reference

Review available API endpoints.

Saved source versions

GET /sources lists accessible versions with a next_cursor for pagination. GET /sources/{source_id} returns the authorized extraction and location offsets; GET /sources/{source_id}/original downloads its original bytes privately. These routes require authentication and recheck source access for each request. Upload a new version through POST /parse-file?supersedes_source_id={source_id} with the original file as multipart form data. Only the owner can add a version, and the supplied ID must be the latest version. Existing references stay pinned. Owners manage explicit teammate access using POST /sources/{source_id}/grants with user_id, org_id and can_use (false means read-only). Both users must be active workspace members. Grants cover all versions. DELETE /sources/{source_id}/grants/{recipient_id} revokes a grant; POST /sources/{source_id}/revoke permanently revokes the source lineage for future use. Generation resolves stored IDs and permissions before charging and rechecks them at later execution boundaries. Release also rechecks source fingerprints and access. Client-supplied extracted text cannot establish permission or coverage.

​Generation Overview

Template

Style

Input

Request ID

​Request

​Uploaded sources

​Response

​Core Request Fields

​Core Request Pattern

​Best Practice

Check Generation Status

Endpoints Reference

​Saved source versions

Generation Overview

Request

Uploaded sources

Response

Core Request Fields

Core Request Pattern

Best Practice

Saved source versions