API Reference

Complete reference for the Helix Writer API.

Base URL

https://api.feeds.onhelix.ai

Authentication

All requests require API key authentication using the Bearer token scheme:

Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for details on obtaining and using API keys.

Create Writer

Create a new writer with a configured style, tone, and quality settings.

POST /writers

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body:

{
  "name": "Tech Blog Writer",
  "description": "Writes technical blog posts for developers",
  "styleGuide": "Use clear, direct language. Avoid jargon unless necessary.",
  "toneMatrix": { "formality": "casual", "enthusiasm": "high" },
  "audienceProfile": "Software engineers with 2-10 years of experience",
  "maxLength": 2000,
  "minLength": 500,
  "humanize": true
}

Parameters:

Parameter	Type	Required	Description
`name`	string	Yes	Writer name (1--256 chars, unique per org)
`description`	string	No	Writer description (1--2,000 chars)
`styleGuide`	string	No	Writing style instructions (1--10,000 chars)
`toneMatrix`	object	No	Key-value tone dimensions
`exampleBank`	string[]	No	Example texts for style matching (max 100 items, 1,000 chars each)
`bannedLanguage`	string[]	No	Words/phrases to avoid (max 100 items, 1,000 chars each)
`constitution`	string[]	No	Rules the AI must follow (max 100 items, 1,000 chars each)
`audienceProfile`	string	No	Target audience description (1--2,000 chars)
`maxLength`	integer	No	Maximum word count (min 1)
`minLength`	integer	No	Minimum word count (min 1)
`formattingRules`	string	No	Formatting instructions (1--5,000 chars)
`maxEditPasses`	integer	No	Max edit iterations (1--50, default: 3)
`qualityThreshold`	number	No	Quality score threshold (0--1, default: 0.7)
`evaluationDimensions`	string[]	No	Quality evaluation criteria (max 100 items, 1,000 chars each, default: see below)
`structuredOutputSchema`	object	No	JSON schema for structured output
`humanize`	boolean	No	Remove AI patterns (default: true)
`otherInstructions`	string	No	Additional instructions (1--10,000 chars)
`contentBriefTemplate`	string	No	Content structure template (1--10,000 chars)

The default evaluationDimensions are: ["clarity", "completeness", "tone", "coherence", "accuracy"].

Response

Status: 201 Created

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organizationId": "org-uuid-here",
    "name": "Tech Blog Writer",
    "description": "Writes technical blog posts for developers",
    "styleGuide": "Use clear, direct language. Avoid jargon unless necessary.",
    "toneMatrix": { "formality": "casual", "enthusiasm": "high" },
    "exampleBank": [],
    "bannedLanguage": [],
    "constitution": [],
    "audienceProfile": "Software engineers with 2-10 years of experience",
    "maxLength": 2000,
    "minLength": 500,
    "formattingRules": null,
    "maxEditPasses": 3,
    "qualityThreshold": 0.7,
    "evaluationDimensions": [
      "clarity",
      "completeness",
      "tone",
      "coherence",
      "accuracy"
    ],
    "structuredOutputSchema": null,
    "humanize": true,
    "otherInstructions": null,
    "contentBriefTemplate": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:00.000Z",
    "deletedAt": null
  }
}

Response Fields:

Field	Type	Description
`id`	string	Unique writer identifier
`organizationId`	string	Organization this writer belongs to
`name`	string	Writer name
`description`	string \| null	Writer description
`styleGuide`	string \| null	Writing style instructions
`toneMatrix`	object \| null	Key-value tone dimensions
`exampleBank`	string[]	Example texts for style matching
`bannedLanguage`	string[]	Words/phrases to avoid
`constitution`	string[]	Rules the AI must follow
`audienceProfile`	string \| null	Target audience description
`maxLength`	integer \| null	Maximum word count
`minLength`	integer \| null	Minimum word count
`formattingRules`	string \| null	Formatting instructions
`maxEditPasses`	integer	Max edit iterations
`qualityThreshold`	number	Quality score threshold
`evaluationDimensions`	string[]	Quality evaluation criteria
`structuredOutputSchema`	object \| null	JSON schema for structured output
`humanize`	boolean	Whether AI pattern removal is enabled
`otherInstructions`	string \| null	Additional instructions
`contentBriefTemplate`	string \| null	Content structure template
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp
`deletedAt`	string \| null	ISO 8601 deletion timestamp, or null

Errors

400 Bad Request:

{
  "success": false,
  "error": "Validation error: name must be at least 1 character"
}

{
  "success": false,
  "error": "A writer with this name already exists in your organization"
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

Example

curl -X POST https://api.feeds.onhelix.ai/writers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Blog Writer",
    "description": "Writes technical blog posts for developers",
    "styleGuide": "Use clear, direct language. Avoid jargon unless necessary.",
    "audienceProfile": "Software engineers with 2-10 years of experience",
    "maxLength": 2000,
    "minLength": 500
  }'

List Writers

Retrieve all writers for your organization.

GET /writers

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Response

Status: 200 OK

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organizationId": "org-uuid-here",
      "name": "Tech Blog Writer",
      "description": "Writes technical blog posts for developers",
      "styleGuide": "Use clear, direct language. Avoid jargon unless necessary.",
      "toneMatrix": { "formality": "casual", "enthusiasm": "high" },
      "exampleBank": [],
      "bannedLanguage": [],
      "constitution": [],
      "audienceProfile": "Software engineers with 2-10 years of experience",
      "maxLength": 2000,
      "minLength": 500,
      "formattingRules": null,
      "maxEditPasses": 3,
      "qualityThreshold": 0.7,
      "evaluationDimensions": [
        "clarity",
        "completeness",
        "tone",
        "coherence",
        "accuracy"
      ],
      "structuredOutputSchema": null,
      "humanize": true,
      "otherInstructions": null,
      "contentBriefTemplate": null,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z",
      "deletedAt": null
    }
  ]
}

Errors

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

Example

curl https://api.feeds.onhelix.ai/writers \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Writer

Retrieve a specific writer by ID.

GET /writers/:writerId

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
`writerId`	string	Yes	Writer identifier

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organizationId": "org-uuid-here",
    "name": "Tech Blog Writer",
    "description": "Writes technical blog posts for developers",
    "styleGuide": "Use clear, direct language. Avoid jargon unless necessary.",
    "toneMatrix": { "formality": "casual", "enthusiasm": "high" },
    "exampleBank": [],
    "bannedLanguage": [],
    "constitution": [],
    "audienceProfile": "Software engineers with 2-10 years of experience",
    "maxLength": 2000,
    "minLength": 500,
    "formattingRules": null,
    "maxEditPasses": 3,
    "qualityThreshold": 0.7,
    "evaluationDimensions": [
      "clarity",
      "completeness",
      "tone",
      "coherence",
      "accuracy"
    ],
    "structuredOutputSchema": null,
    "humanize": true,
    "otherInstructions": null,
    "contentBriefTemplate": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:00.000Z",
    "deletedAt": null
  }
}

Errors

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Writer not found: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example

curl https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Writer

Update an existing writer's configuration. Only fields included in the request body are updated.

PATCH /writers/:writerId

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Path Parameters:

Parameter	Type	Required	Description
`writerId`	string	Yes	Writer identifier

Body:

{
  "styleGuide": "Use a more formal tone. Avoid contractions.",
  "maxLength": 3000
}

Parameters:

Accepts all fields from Create Writer. All fields are optional; only fields present in the request body are modified.

Sending an empty body {} is a valid request -- it updates only the updatedAt timestamp.

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organizationId": "org-uuid-here",
    "name": "Tech Blog Writer",
    "description": "Writes technical blog posts for developers",
    "styleGuide": "Use a more formal tone. Avoid contractions.",
    "toneMatrix": { "formality": "casual", "enthusiasm": "high" },
    "exampleBank": [],
    "bannedLanguage": [],
    "constitution": [],
    "audienceProfile": "Software engineers with 2-10 years of experience",
    "maxLength": 3000,
    "minLength": 500,
    "formattingRules": null,
    "maxEditPasses": 3,
    "qualityThreshold": 0.7,
    "evaluationDimensions": [
      "clarity",
      "completeness",
      "tone",
      "coherence",
      "accuracy"
    ],
    "structuredOutputSchema": null,
    "humanize": true,
    "otherInstructions": null,
    "contentBriefTemplate": null,
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-01-15T11:30:00.000Z",
    "deletedAt": null
  }
}

Errors

400 Bad Request:

{
  "success": false,
  "error": "Validation error: maxLength must be at least 1"
}

{
  "success": false,
  "error": "A writer with this name already exists in your organization"
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Writer not found: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example

curl -X PATCH https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "styleGuide": "Use a more formal tone. Avoid contractions.",
    "maxLength": 3000
  }'

Delete Writer

Delete a writer. The writer is soft-deleted and will no longer appear in list results or accept new jobs. Existing in-progress jobs are not affected, and completed job results remain retrievable using the original writerId.

DELETE /writers/:writerId

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
`writerId`	string	Yes	Writer identifier

Response

Status: 204 No Content

No response body is returned.

Errors

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Writer not found: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Example

curl -X DELETE https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

Start Writing Job

Submit a writing request to a writer. Returns immediately with a job ID. The writing job runs asynchronously -- poll the status endpoint or retrieve results when ready.

POST /writers/:writerId/jobs

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Path Parameters:

Parameter	Type	Required	Description
`writerId`	string	Yes	Writer identifier

Body:

{
  "prompt": "Write a blog post about the benefits of TypeScript for large codebases.",
  "jobId": "my-blog-post-job-001",
  "research": "TypeScript adoption has grown 50% year-over-year according to the Stack Overflow survey...",
  "toneContext": "The audience just attended a conference on developer productivity"
}

Parameters:

Parameter	Type	Required	Description
`prompt`	string	Yes	Writing instruction (1--100,000 chars)
`jobId`	string	No	Idempotency key (1--256 chars, alphanumeric, hyphens, underscores)
`research`	string	No	Research context to inform the writing (1--100,000 chars)
`toneContext`	string	No	Per-job tone guidance (1--10,000 chars)
`overrides`	object	No	Override writer profile fields for this job only. Only fields valid on a writer profile are accepted.

Response

Status: 202 Accepted

{
  "success": true,
  "data": {
    "jobId": "my-blog-post-job-001"
  }
}

Response Fields:

Field	Type	Description
`jobId`	string	Job identifier. Use this to check status and retrieve results

Idempotency

Submitting a request with an existing jobId reconnects to the running, pending, or completed job instead of starting a new one. If the previous job with that jobId failed, the API returns a 400 error -- use a new jobId to retry.

Errors

400 Bad Request:

{
  "success": false,
  "error": "Validation error: prompt must be at least 1 character"
}

{
  "success": false,
  "error": "Previous writer job failed. Please retry with a new jobId."
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Writer not found: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

500 Internal Server Error:

{
  "success": false,
  "error": "Failed to start writer job."
}

Example

curl -X POST https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a blog post about the benefits of TypeScript for large codebases.",
    "jobId": "my-blog-post-job-001"
  }'

Check Job Status

Check the current status of a writing job.

GET /writers/:writerId/jobs/:jobId/status

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
`writerId`	string	Yes	Writer identifier
`jobId`	string	Yes	Job identifier (`[a-zA-Z0-9_-]+`)

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "jobId": "my-blog-post-job-001",
    "status": "running"
  }
}

Response Fields:

Field	Type	Description
`jobId`	string	Job identifier
`status`	string	Current job status

Status Values:

Status	Description
`pending`	Job created, workflow starting
`running`	Job actively processing
`completed`	Job finished, results available
`failed`	Job failed

Errors

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Job not found: my-blog-post-job-001"
}

Example

curl "https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/jobs/my-blog-post-job-001/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Job Result

Retrieve the result of a completed writing job.

GET /writers/:writerId/jobs/:jobId

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
`writerId`	string	Yes	Writer identifier
`jobId`	string	Yes	Job identifier (`[a-zA-Z0-9_-]+`)

Important: Always check the job status endpoint first. Calling this endpoint on a pending or running job returns a 500 error, not a partial result.

Response

Status: 200 OK

The response shape depends on whether the writer was configured with a structuredOutputSchema.

Plain text result (no structuredOutputSchema):

{
  "success": true,
  "data": {
    "status": "completed",
    "content": "TypeScript has transformed how teams build large-scale applications...",
    "outline": {
      "sections": [
        {
          "title": "Introduction",
          "summary": "Overview of TypeScript adoption"
        },
        { "title": "Type Safety at Scale", "summary": "How types prevent bugs" }
      ]
    },
    "metadata": {
      "wordCount": 1243,
      "editPasses": 2,
      "qualityScore": 0.89
    }
  }
}

Structured result (with structuredOutputSchema):

{
  "success": true,
  "data": {
    "status": "completed",
    "structuredContent": {
      "title": "Why TypeScript Is Essential for Large Codebases",
      "sections": [
        {
          "heading": "Introduction",
          "body": "TypeScript has transformed how teams build large-scale applications..."
        }
      ],
      "summary": "A comprehensive look at TypeScript's benefits for enterprise teams."
    },
    "outline": {
      "sections": [
        {
          "title": "Introduction",
          "summary": "Overview of TypeScript adoption"
        },
        { "title": "Type Safety at Scale", "summary": "How types prevent bugs" }
      ]
    },
    "metadata": {
      "wordCount": 1243,
      "editPasses": 2,
      "qualityScore": 0.89
    }
  }
}

Response Fields:

Field	Type	Description
`status`	string	Job status (`completed`). For failed jobs, this endpoint returns a 500 error -- check the status endpoint first.
`content`	string	Written content as plain text (present when no `structuredOutputSchema`)
`structuredContent`	object	Written content conforming to the writer's `structuredOutputSchema` (present when schema is configured)
`outline`	object	The structural outline generated before writing
`metadata`	object	Job metadata including word count, edit passes, and quality score

Errors

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found:

{
  "success": false,
  "error": "Job not found: my-blog-post-job-001"
}

500 Internal Server Error:

{
  "success": false,
  "error": "Writer job failed. Please retry with a new jobId."
}

{
  "success": false,
  "error": "Writer job is still processing. Poll GET /writers/:writerId/jobs/:jobId/status and retry when completed."
}

Handling Failed Jobs

If a job fails:

The status endpoint reports failed
The result endpoint returns a 500 error -- failure details are not currently exposed in the API response
Retry by submitting a new job with a different jobId

Common causes of job failure include workflow timeouts (jobs exceeding 60 minutes) and transient infrastructure errors.

Example

curl "https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/jobs/my-blog-post-job-001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

All endpoints may return these standard errors:

400 Bad Request

Invalid request parameters or body:

{
  "success": false,
  "error": "Validation error: name must be at least 1 character"
}

401 Unauthorized

Missing or invalid API key:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found

Resource not found:

{
  "success": false,
  "error": "Writer not found: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

500 Internal Server Error

Server error:

{
  "success": false,
  "error": "An internal error occurred. Please try again later."
}

Next Steps

Quickstart Guide: Get started in under 5 minutes
Overview: Understand how the Writer works
Concepts: Key concepts and terminology
Authentication: API key best practices

API Reference

Base URL​

Authentication​

Create Writer​

Request​

Response​

Errors​

Example​

List Writers​

Request​

Response​

Errors​

Example​

Get Writer​

Request​

Response​

Errors​

Example​

Update Writer​

Request​

Response​

Errors​

Example​

Delete Writer​

Request​

Response​

Errors​

Example​

Start Writing Job​

Request​

Response​

Idempotency​

Errors​

Example​

Check Job Status​

Request​

Response​

Errors​

Example​

Get Job Result​

Request​

Response​

Errors​

Handling Failed Jobs​

Example​

Error Responses​

400 Bad Request​

401 Unauthorized​

404 Not Found​

500 Internal Server Error​

Next Steps​

Base URL

Authentication

Create Writer

Request

Response

Errors

Example

List Writers

Request

Response

Errors

Example

Get Writer

Request

Response

Errors

Example

Update Writer

Request

Response

Errors

Example

Delete Writer

Request

Response

Errors

Example

Start Writing Job

Request

Response

Idempotency

Errors

Example

Check Job Status

Request

Response

Errors

Example

Get Job Result

Request

Response

Errors

Handling Failed Jobs

Example

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Next Steps