article-generation

Article Generation

Generate articles from discovered topics. Generation is asynchronous — you receive a job ID and poll for completion.

Pre-Flight Check

Always check credits before generating:

GET /v1/account

If canGenerate is false, inform the user they need to upgrade or wait for their billing period to reset. Do not attempt generation.

Generate Article

POST /v1/articles/generate

Body:

{
  "topicId": "uuid",
  "language": "en",
  "translationLanguages": ["es", "fr"],
  "customFields": { "tone": "professional" }
}

Field	Type	Required	Description
topicId	string	Yes	ID of the topic to generate from
language	string	Yes	Primary language code
translationLanguages	string[]	No	Additional languages to translate into
customFields	object	No	Custom metadata (key-value string pairs)

Response (202 Accepted):

{
  "jobId": "uuid",
  "status": "queued",
  "estimatedCompletionTime": "2026-03-07T12:30:00Z",
  "statusUrl": "/api/v1/jobs/{jobId}",
  "translationLanguages": ["es", "fr"]
}

Check Job Status

GET /v1/jobs/:jobId

Response:

{
  "job": {
    "jobId": "uuid",
    "type": "article_generation",
    "state": "completed",
    "progress": 100,
    "currentStep": "done",
    "output": {
      "articleId": "uuid",
      "translationJobIds": ["tid1", "tid2"]
    }
  }
}

Job states: queued, processing, completed, failed

List Active Jobs

GET /v1/jobs

Returns all jobs with state queued or processing.

Polling Workflow

Follow this sequence for article generation with translations:

1. Check credits — GET /v1/account, verify canGenerate is true
2. Generate — POST /v1/articles/generate with topicId, language, and optional translationLanguages
3. Poll primary job — GET /v1/jobs/:jobId every 10-15 seconds until state is completed or failed
4. On completion — output.articleId is the generated article, output.translationJobIds contains translation jobs
5. Poll translation jobs — GET /v1/jobs/:translationJobId for each until all are completed
6. Retrieve articles — GET /v1/articles/:articleId for the primary article and each translation

Polling interval: 10-15 seconds. Do not poll more frequently.

On failure: Report the error to the user. Do not retry automatically.

Error Codes

Status	Code	Meaning
404	TOPIC_NOT_FOUND	Topic doesn't exist or not owned by user
409	ARTICLE_EXISTS	Article already exists for this topic+language
409	JOB_IN_PROGRESS	Generation already queued for this topic+language
403	CREDIT_LIMIT_REACHED	No remaining credits this billing period
503	SERVICE_BUSY	System busy — try again in a moment

Workflows

Generate article with Spanish and French translations

1. GET /v1/account — verify credits
2. POST /v1/articles/generate with { "topicId": "...", "language": "en", "translationLanguages": ["es", "fr"] }
3. Poll GET /v1/jobs/:jobId until completed
4. Get translationJobIds from output
5. Poll each translation job until completed
6. Report all article IDs to user

Check on a running job

1. GET /v1/jobs/:jobId
2. Report state and progress to user