Skip to main content

Quickstart

Get started with Helix Writer in under 5 minutes. This guide walks you through creating a writer profile, submitting a writing job, and retrieving the results.

Prerequisites​

Before you begin, you'll need:

Step 1: Create a Writer​

A writer profile defines how your content should be written -- the tone, style, and quality standards. Create one before submitting any jobs.

curl -X POST https://api.feeds.onhelix.ai/writers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog Writer",
    "description": "Writes engaging blog posts in a conversational tone",
    "styleGuide": "Write in a conversational, approachable tone. Use short paragraphs. Address the reader directly with \"you\". Avoid jargon unless explaining it."
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Blog Writer",
    "description": "Writes engaging blog posts in a conversational tone",
    "styleGuide": "Write in a conversational, approachable tone. Use short paragraphs. Address the reader directly with \"you\". Avoid jargon unless explaining it.",
    "humanize": true,
    "qualityThreshold": 0.7,
    "maxEditPasses": 3,
    "evaluationDimensions": [
      "clarity",
      "completeness",
      "tone",
      "coherence",
      "accuracy"
    ],
    "createdAt": "2026-03-23T12:00:00.000Z",
    "updatedAt": "2026-03-23T12:00:00.000Z",
    "deletedAt": null,
    "...": "other fields omitted — see API Reference for full response"
  }
}

Save the id value -- you'll need it to submit jobs and retrieve results.

Step 2: Start a Writing Job​

Submit a prompt to your writer. The job runs asynchronously, so you'll get back a jobId to track progress.

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 500-word blog post about the benefits of remote work for software engineering teams. Include practical tips and address common concerns."
  }'

Response (202 Accepted):

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Save the jobId value -- you'll need it to check status and retrieve results.

Writing jobs typically take 1--5 minutes depending on content length and quality settings. Poll every 5--10 seconds until the status is completed or failed.

Step 3: Check Status​

Poll the status endpoint until the job completes:

curl "https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/jobs/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "running"
  }
}

Status values:

  • pending -- job created, workflow starting
  • running -- job actively processing
  • completed -- job finished, results available
  • failed -- job failed

The job is complete when status is completed or failed. Keep polling while status is pending or running.

Step 4: Get the Result​

Once the status is completed, retrieve the written content:

curl "https://api.feeds.onhelix.ai/writers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/jobs/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "status": "completed",
    "content": "Remote work has transformed how software teams operate -- and for good reason. When you remove the daily commute and open-office distractions, engineers can focus in ways that simply aren't possible in a traditional office.\n\nThe productivity gains are real. Studies consistently show that developers working remotely report longer stretches of uninterrupted focus time. You're in control of your environment: the temperature, the noise level, the ergonomics of your setup. That kind of autonomy has a direct impact on output quality.\n\nOf course, remote work comes with its own challenges. Communication takes more intentional effort when you're not sharing a physical space. The teams that make it work invest in clear async documentation, structured check-ins, and tools that keep everyone aligned without requiring constant video calls.",
    "outline": { ... },
    "metadata": { ... }
  }
}

Structured Output Example​

If you need your content in a consistent, machine-readable format, set a structuredOutputSchema on the writer. The output will be returned in the structuredContent field instead of content.

Create a New Writer with Structured Output​

Create a second writer configured for structured output:

curl -X POST https://api.feeds.onhelix.ai/writers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Description Writer",
    "styleGuide": "Write compelling, benefit-focused product descriptions.",
    "structuredOutputSchema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "tagline": { "type": "string" },
        "features": { "type": "array", "items": { "type": "string" } },
        "seoKeywords": { "type": "array", "items": { "type": "string" } },
        "metaDescription": { "type": "string" }
      }
    }
  }'

Start a Job​

curl -X POST https://api.feeds.onhelix.ai/writers/b2c3d4e5-f6a7-8901-bcde-f12345678901/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a product description for a mechanical keyboard aimed at software developers. The keyboard has a compact 75% layout, tactile switches, and a USB-C connection."
  }'

Retrieve the Structured Result​

{
  "success": true,
  "data": {
    "status": "completed",
    "structuredContent": {
      "title": "Developer 75 Mechanical Keyboard",
      "tagline": "Compact layout. Tactile feel. Built for the way you code.",
      "features": [
        "75% compact layout keeps everything you need without the bulk",
        "Tactile switches provide satisfying feedback on every keystroke",
        "USB-C connection for a reliable, modern cable setup",
        "Optimized key spacing reduces finger travel and fatigue during long sessions"
      ],
      "seoKeywords": [
        "mechanical keyboard for developers",
        "75% layout keyboard",
        "tactile switch keyboard",
        "compact programming keyboard",
        "USB-C mechanical keyboard"
      ],
      "metaDescription": "The Developer 75 mechanical keyboard offers a compact 75% layout with tactile switches and USB-C connectivity -- designed for software developers who want precision and comfort without a full-size footprint."
    },
    "outline": { ... },
    "metadata": { ... }
  }
}

Common Patterns​

Polling with Retry​

WRITER_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
JOB_ID="550e8400-e29b-41d4-a716-446655440000"
MAX_ATTEMPTS=120  # 10 minutes at 5-second intervals
ATTEMPT=0

while true; do
  STATUS=$(curl -s "https://api.feeds.onhelix.ai/writers/$WRITER_ID/jobs/$JOB_ID/status" \
    -H "Authorization: Bearer YOUR_API_KEY" | jq -r '.data.status')

  echo "Attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS -- status: $STATUS"

  if [ "$STATUS" = "completed" ]; then
    echo "Job completed successfully. Fetching result..."
    curl "https://api.feeds.onhelix.ai/writers/$WRITER_ID/jobs/$JOB_ID" \
      -H "Authorization: Bearer YOUR_API_KEY"
    break
  fi

  if [ "$STATUS" = "failed" ]; then
    echo "Job failed. Retry with a new jobId."
    break
  fi

  ATTEMPT=$((ATTEMPT + 1))
  if [ "$ATTEMPT" -ge "$MAX_ATTEMPTS" ]; then
    echo "Timed out after $MAX_ATTEMPTS attempts."
    break
  fi

  sleep 5
done

Using Research Context​

Provide source material or factual context that the writer should draw from:

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 summary of our Q1 product updates for the company blog.",
    "research": "Q1 highlights: launched dark mode in January (most-requested feature, 12k upvotes), reduced API latency by 40% in February through query optimization, added Slack and GitHub integrations in March with 2,300 teams connected in the first week."
  }'

The research field gives the writer grounded facts to work from, reducing hallucination and keeping the output accurate to your source material.

Using Per-Job Overrides​

Override writer settings for a single job without modifying the writer profile:

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 brief announcement for our enterprise customers about the upcoming maintenance window.",
    "overrides": {
      "styleGuide": "Use a formal, professional tone. Be concise and direct. Include all relevant details upfront.",
      "maxLength": 150
    }
  }'

Overrides apply only to this job. The writer profile remains unchanged.

Next Steps​