Aautoranko

API reference

Generation jobs

A job is one article generation: you send a topic, Autoranko builds an SEO outline and writes the full article, then holds it for your review or publishes it to WordPress. Jobs run in the background; follow them by polling or with webhooks.

4 endpointsBase URL https://autoranko.com/api/public/v1Every request needs a bearer token

Job lifecycle

A job moves through these statuses by itself. Your calls only start it (POST /sites/{id}/jobs) and approve it (POST /jobs/{id}/publish). Follow it by polling GET /jobs/{id}, or let the job.review, job.published and job.failed webhooks tell you.

  1. Review first

    auto_publish off (the default). The draft waits in review until you call POST /jobs/{id}/publish.

    1. pending
    2. generating
    3. reviewfires job.review
    4. publishing
    5. publishedfires job.published
  2. Autopilot

    auto_publish on and WordPress connected (wp_connected: true). Without the connection the job stops in review.

    1. pending
    2. generating
    3. publishing
    4. publishedfires job.published
  3. Generation fails

    error says why. Failed jobs don't count toward the allowance; create a new job to try again.

    1. pending
    2. generating
    3. failedfires job.failed
  4. WordPress rejects the post

    The job returns to review with error set (Publishing failed: …). Fix the cause, then publish again.

    1. publishing
    2. reviewfires job.review
    3. publishing
  5. Stuck job recovered

    Still generating after an hour (a server restart, say): reset to pending and retried automatically.

    1. generating
    2. pending
    3. generating
StatusMeaningMoves to
pendingCreated and waiting to start. Immediate jobs start within seconds; scheduled jobs start once scheduled_for has passed (the scheduler runs every minute).generating
generatingAutoranko is writing the outline, then the full article. This usually takes a few minutes. A job stuck here for over an hour (after a server restart, for example) is reset to pending and retried automatically.reviewpublishingfailedpending
reviewjob.reviewThe draft is ready and waiting for approval: auto_publish was off, the site has no WordPress connection, or a publish attempt failed (then error says why). Publish it with POST /jobs/{id}/publish.publishing
publishingThe article is being sent to WordPress. If WordPress rejects it, the job goes back to review.publishedreview
publishedjob.publishedThe article is live on WordPress, and wp_post_id holds the post ID.Final
failedjob.failedGeneration failed, and error says why. Failed jobs don't count toward the plan's allowance; create a new job to try again.Final

List jobs

GEThttps://autoranko.com/api/public/v1/sites/{id}/jobs

Lists the site's generation jobs, newest first, including jobs created in the dashboard. The list leaves out the heavy fields (outline and article_html); fetch a single job with GET /jobs/{id} for those.

Filter with status to build a review queue (review) or catch failures (failed). The endpoint returns the newest limit jobs (up to 200) and has no offset.

Request

Path parameters
Query parameters
  • statusstringOptional
    Only return jobs in this status. An unknown value returns an empty list, not an error.

    One ofpendinggeneratingreviewpublishingpublishedfailed

    Example
    review
  • limitintegerOptional
    How many of the newest jobs to return. Values outside 1–200 are clamped to that range.
    Default
    50
    Range
    1–200
    Example
    20
curl "https://autoranko.com/api/public/v1/sites/1/jobs?status=review&limit=20" \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKThe newest jobs, optionally filtered by status.

Response bodyapplication/json
  • jobsarray of objects
    Jobs, newest first.
    jobs items(13)Job
    • idstring
      Job ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site the article is for.
    • topicstring
      The topic the article was requested for.
    • target_keywordstring or null
      The keyword the article targets, or null.
    • statusstring
      Where the job is in its lifecycle: pending → generating → review or publishing → published, or failed.

      One ofpendinggeneratingreviewpublishingpublishedfailed

    • article_titlestring or null
      Title chosen in the outline step; null until the draft is ready.
    • meta_descriptionstring or null
      SEO meta description (aimed at under 160 characters), also used as the WordPress excerpt; null until the draft is ready.
    • wp_post_idstring or null
      ID of the WordPress post once published (a 64-bit integer serialized as a string), otherwise null.
    • auto_publishboolean
      Whether the job publishes to WordPress by itself when the draft is ready.
    • scheduled_forstring (date-time) or null
      When a scheduled job is due to start, or null for a job that started immediately.
    • errorstring or null
      Why the job failed, or why the last publish attempt failed (it then starts with Publishing failed:); null otherwise.
    • created_atstring (date-time)
      When the job was created.
    • updated_atstring (date-time)
      When the job last changed.

Example

Recent jobs

GET/sites/1/jobs

Response · 200 OK
{
  "jobs": [
    {
      "id": "3",
      "site_id": "1",
      "topic": "How to winterize a sprinkler system before the first freeze",
      "target_keyword": "winterize sprinkler system",
      "status": "review",
      "article_title": "How to Winterize a Sprinkler System Before the First Freeze",
      "meta_description": "Learn how to winterize a sprinkler system before the first freeze, with steps for shutting off water, draining lines and protecting equipment.",
      "wp_post_id": null,
      "auto_publish": false,
      "scheduled_for": null,
      "error": "Publishing failed: WordPress publishing is not authorized for this site.",
      "created_at": "2026-10-25T20:10:51.035Z",
      "updated_at": "2026-10-25T20:42:05.140Z"
    }
  ]
}

Captured from the live API, with a seeded sample job left out. The error comes from a publish attempt on a site without a WordPress connection.

Errors

ErrorWhen
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
404not_foundNo site with this id belongs to your account (Site not found.).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.

Create a job

POSThttps://autoranko.com/api/public/v1/sites/{id}/jobs

Starts writing a new article for the site. Autoranko builds an SEO outline for your topic (title, meta description, sections and FAQs, planned at about 1,800 words), then writes the full article as HTML. The call returns 201 right away with the job in pending; generation runs in the background and usually takes a few minutes.

What happens when the draft is ready depends on auto_publish. Off (the default): the job stops in review and fires job.review, so you can read it and then call POST /jobs/{id}/publish. On, with WordPress connected (wp_connected: true): it continues to publishing and published by itself. On, without a WordPress connection: it stops in review.

Pass scheduled_for to queue the job for later instead of starting now. A scheduler checks every minute and starts due jobs, oldest first, up to 5 per run.

Every job counts toward the site's article allowance as soon as it's created (Free: 3 in total; Starter: 8 per calendar month; Pro: 30 per calendar month). Jobs that end in failed don't count. Once the allowance is used up, this endpoint returns 429 plan_limit.

There's no idempotency key. If a create request times out, check GET /sites/{id}/jobs before retrying, or you may generate the same article twice and use up allowance for it.

Request

Path parameters
Body parametersapplication/json
  • topicstringRequired
    What the article should be about: a working title, a question or a short brief. Surrounding whitespace is trimmed; 1–300 characters remain.
    Length
    1–300 characters
    Example
    How to winterize a sprinkler system before the first freeze
  • target_keywordstringOptional
    The search query the article should rank for. It steers the outline, headings and on-page SEO. Omit it, or send an empty string, for none.
    Example
    winterize sprinkler system
  • auto_publishbooleanOptional
    Publish to WordPress as soon as the draft is ready instead of stopping in review. Needs the site's WordPress connection (wp_connected: true); without it the job stops in review. Send a JSON boolean: any truthy value, even the string "false", turns it on.
    Default
    false
    Example
    false
  • scheduled_forstring (date-time)Optional
    Start generating at this time instead of now: an ISO 8601 date-time such as 2026-11-02T09:00:00Z. Include Z or an offset; times without one are treated as UTC. A time in the past starts the job on the scheduler's next run, within about a minute.
    Example
    2026-11-02T09:00:00Z
curl -X POST https://autoranko.com/api/public/v1/sites/1/jobs \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "How to winterize a sprinkler system before the first freeze",
    "target_keyword": "winterize sprinkler system",
    "auto_publish": false
  }'

Response

201CreatedThe job was created in pending.

Response bodyapplication/json
  • jobobject
    The new job.
    job keys(11)NewJob
    • idstring
      Job ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site the article is for.
    • topicstring
      The topic the article was requested for.
    • target_keywordstring or null
      The keyword the article targets, or null.
    • statusstring
      Where the job is in its lifecycle: pending → generating → review or publishing → published, or failed.

      One ofpendinggeneratingreviewpublishingpublishedfailed

    • article_titlestring or null
      Title chosen in the outline step; null until the draft is ready.
    • meta_descriptionstring or null
      SEO meta description (aimed at under 160 characters), also used as the WordPress excerpt; null until the draft is ready.
    • wp_post_idstring or null
      ID of the WordPress post once published (a 64-bit integer serialized as a string), otherwise null.
    • auto_publishboolean
      Whether the job publishes to WordPress by itself when the draft is ready.
    • scheduled_forstring (date-time) or null
      When a scheduled job is due to start, or null for a job that started immediately.
    • created_atstring (date-time)
      When the job was created.

Examples

POST/sites/1/jobsIllustrative

Request body
{
  "topic": "How to winterize a sprinkler system before the first freeze",
  "target_keyword": "winterize sprinkler system",
  "auto_publish": false
}
Response · 201 Created
{
  "job": {
    "id": "3",
    "site_id": "1",
    "topic": "How to winterize a sprinkler system before the first freeze",
    "target_keyword": "winterize sprinkler system",
    "status": "pending",
    "article_title": null,
    "meta_description": null,
    "wp_post_id": null,
    "auto_publish": false,
    "scheduled_for": null,
    "created_at": "2026-10-25T20:10:51.035Z"
  }
}

Reconstructed from the live job 3 as the API returned it at creation.

Errors

ErrorWhen
400invalid_bodyThe body isn't valid JSON (Invalid JSON body.).
400invalid_bodytopic is missing or blank (topic is required.).
400invalid_bodytopic is longer than 300 characters (topic is too long (max 300 chars).).
400invalid_bodyscheduled_for can't be parsed as a date-time (scheduled_for must be an ISO 8601 datetime.).
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
404not_foundNo site with this id belongs to your account (Site not found.).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.
429plan_limitThe site has used its article allowance (Free: 3 in total; Starter: 8 per calendar month; Pro: 30 per calendar month).

Get a job

GEThttps://autoranko.com/api/public/v1/jobs/{id}

Returns one job with everything generated so far. outline and article_html are null until the draft is finished; then they hold the structured outline and the full article HTML that will be published.

To follow a job, poll this endpoint every 15–30 seconds until status is review, published or failed, or subscribe to webhooks and skip polling. error explains a failed job. On a job back in review, it holds the reason the last publish attempt failed (starting with Publishing failed:) and is cleared when a later publish succeeds.

Polling every 15–30 seconds per job stays far below the rate limit. With many jobs in flight, prefer webhooks.

Request

Path parameters
curl https://autoranko.com/api/public/v1/jobs/3 \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKThe job, with its outline and article HTML once generated.

Response bodyapplication/json
  • jobobject
    The job.
    job keys(15)JobDetail
    • idstring
      Job ID: a 64-bit integer serialized as a string.
    • site_idstring
      ID of the site the article is for.
    • topicstring
      The topic the article was requested for.
    • target_keywordstring or null
      The keyword the article targets, or null.
    • statusstring
      Where the job is in its lifecycle: pending → generating → review or publishing → published, or failed.

      One ofpendinggeneratingreviewpublishingpublishedfailed

    • article_titlestring or null
      Title chosen in the outline step; null until the draft is ready.
    • meta_descriptionstring or null
      SEO meta description (aimed at under 160 characters), also used as the WordPress excerpt; null until the draft is ready.
    • wp_post_idstring or null
      ID of the WordPress post once published (a 64-bit integer serialized as a string), otherwise null.
    • auto_publishboolean
      Whether the job publishes to WordPress by itself when the draft is ready.
    • scheduled_forstring (date-time) or null
      When a scheduled job is due to start, or null for a job that started immediately.
    • errorstring or null
      Why the job failed, or why the last publish attempt failed (it then starts with Publishing failed:); null otherwise.
    • outlineobject or null
      The structured outline the article was written from; null until the draft is ready. It's AI-generated JSON: the keys below are requested from the model but not guaranteed.
      outline keys(10)JobOutline
      • titlestringOptional
        Article title.
      • meta_descriptionstringOptional
        SEO meta description.
      • slugstringOptional
        Suggested URL slug.
      • target_keywordstringOptional
        Primary keyword.
      • secondary_keywordsarray of stringsOptional
        Related keywords to work into the article.
      • sectionsarray of objectsOptional
        The article structure, in order.
        sections items(4)
        • levelstring
          Heading level.

          One ofh2h3

        • headingstring
          Section heading.
        • descriptionstring
          What the section covers.
        • word_countinteger
          Planned length of the section in words.
      • faqsarray of objectsOptional
        Questions for the FAQ section.
        faqs items(2)
        • questionstring
          The question.
        • answer_briefstring
          The gist of the answer.
      • image_suggestionsarray of objectsOptional
        Image ideas. The first one is meant as the featured image.
        image_suggestions items(2)
        • descriptionstring
          What the image shows.
        • alt_textstring
          Suggested alt text.
      • google_image_queriesarray of stringsOptional
        Search queries for finding matching images.
      • video_querystringOptional
        Search query for a related video.
    • article_htmlstring or null
      The full article as HTML: headings start at <h2> (the title is separate) and there are no images. null until the draft is ready. This is exactly what gets published.
    • created_atstring (date-time)
      When the job was created.
    • updated_atstring (date-time)
      When the job last changed.

Examples

GET/jobs/3

Response · 200 OK
{
  "job": {
    "id": "3",
    "site_id": "1",
    "topic": "How to winterize a sprinkler system before the first freeze",
    "target_keyword": "winterize sprinkler system",
    "status": "review",
    "article_title": "How to Winterize a Sprinkler System Before the First Freeze",
    "meta_description": "Learn how to winterize a sprinkler system before the first freeze, with steps for shutting off water, draining lines and protecting equipment.",
    "wp_post_id": null,
    "auto_publish": false,
    "scheduled_for": null,
    "error": "Publishing failed: WordPress publishing is not authorized for this site.",
    "outline": {
      "title": "How to Winterize a Sprinkler System Before the First Freeze",
      "meta_description": "Learn how to winterize a sprinkler system before the first freeze, with steps for shutting off water, draining lines and protecting equipment.",
      "slug": "winterize-sprinkler-system",
      "target_keyword": "winterize sprinkler system",
      "secondary_keywords": [
        "sprinkler blowout",
        "drain irrigation lines",
        "insulate backflow preventer"
      ],
      "sections": [
        {
          "level": "h2",
          "heading": "Why winterizing your sprinkler system matters",
          "description": "How trapped water freezes, expands and cracks pipes, fittings and valves.",
          "word_count": 220
        },
        {
          "level": "h2",
          "heading": "Step 1: Shut off the water supply",
          "description": "Find the main shut-off valve and protect it from freezing.",
          "word_count": 180
        }
      ],
      "faqs": [
        {
          "question": "When should I winterize my sprinkler system?",
          "answer_brief": "Before the first hard freeze, once nights approach 32 °F (0 °C)."
        }
      ],
      "image_suggestions": [
        {
          "description": "Homeowner blowing out sprinkler lines with an air compressor in autumn",
          "alt_text": "Blowing out sprinkler lines with an air compressor"
        }
      ],
      "google_image_queries": [
        "sprinkler system blowout"
      ],
      "video_query": "how to winterize a sprinkler system"
    },
    "article_html": "<h2>Why winterizing your sprinkler system matters</h2>\n<p>Water left inside an irrigation system can freeze and expand, cracking pipes, splitting fittings, or damaging valves. Exposed backflow preventers are especially vulnerable because they lack the protection that soil provides to buried components.</p>\n<!-- … shortened for the docs … -->",
    "created_at": "2026-10-25T20:10:51.035Z",
    "updated_at": "2026-10-25T20:42:05.140Z"
  }
}

Captured from the live API. article_html is shortened, and outline is abbreviated to show its structure.

Errors

ErrorWhen
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
404not_foundNo job with this id exists (Job not found.), or it belongs to another account's site (Site not found.).
429rate_limitedThe token made more than 120 requests in the last 60 seconds.

Publish a job

POSThttps://autoranko.com/api/public/v1/jobs/{id}/publish

Approves a job that's waiting in review and publishes it to the site's WordPress as a live post: article_title becomes the post title, article_html the content and meta_description the excerpt. The call returns at once with status set to publishing; the WordPress request runs in the background. No request body is needed.

When it succeeds, the job becomes published, wp_post_id holds the new post's ID and job.published fires with the post URL in wp_link. If WordPress rejects the post, or the site isn't connected (wp_connected: false), the job returns to review with error set (for example Publishing failed: WordPress publishing is not authorized for this site.) and job.review fires with publish_error: true. Fix the cause and call this endpoint again.

Each successful publish creates a new WordPress post. A published job can't be published again (409 invalid_state); to publish the topic again, create a new job.

Request

Path parameters
curl -X POST https://autoranko.com/api/public/v1/jobs/3/publish \
  -H "Authorization: Bearer $AUTORANKO_TOKEN"

Response

200OKPublishing started.

Response bodyapplication/json
  • okboolean
    Always true.
  • statusstring
    The job's new status.

    One ofpublishing

Examples

POST/jobs/3/publish

Response · 200 OK
{
  "ok": true,
  "status": "publishing"
}

Errors

ErrorWhen
401missing_tokenThe Authorization: Bearer … header is missing.
401invalid_tokenThe token is malformed, unknown or revoked.
404not_foundNo job with this id exists (Job not found.), or it belongs to another account's site (Site not found.).
409invalid_stateThe job isn't in review or has no generated article: it's still generating, already publishing or published, or failed.
429rate_limitedThe token made more than 120 requests in the last 60 seconds.

API version v1. Every path on this page is relative to https://autoranko.com/api/public/v1.