Endpoints

The ScribePilot API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

POST/v1/generate

Start Generation

Start async blog post generation. Returns a runId and statusUrl immediately. Poll the statusUrl for progress.

Parameters

ParameterTypeRequiredDescription
topicstringYesThe blog topic (minimum 3 characters)
targetWordCountnumberNoTarget word count (100–5 000). Default: 1500
tonestringNoWriting tone, e.g. "professional", "casual", "technical". Default: "professional"
qualitystringNo"premium" (30 credits/word, Opus), "standard" (20, Sonnet), or "economy" (10, Haiku). Default: "standard"
citationModestringNo"none", "basic", or "academic". Default: "none"
maxAttemptsnumberNoMax write/rewrite attempts (1–5). Default: 5
keywordsstring[]NoSEO keywords to incorporate
categorystringNoBlog category for organization
idempotencyKeystringNoUnique key for duplicate request prevention
optionsobjectNoAdvanced: { customInstructions, sourceUrls, outline }
Request Body
{
  "topic": "The Future of AI in Content Marketing",
  "targetWordCount": 1500,
  "tone": "professional",
  "quality": "standard",
  "keywords": ["AI", "content marketing"],
  "category": "Technology"
}
Response
{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "creditsReserved": 30000,
  "balanceAfter": 270000,
  "statusUrl": "/api/v1/generate/status?runId=550e8400-..."
}
GET/v1/generate/status?runId={runId}

Get Generation Status

Poll for generation progress using the runId from POST /generate. Returns status, currentStep, and progress (0-100).

Parameters

ParameterTypeRequiredDescription
runIdstringYesThe run ID returned from POST /generate (query param)
Response
{
  "runId": "550e8400-...",
  "status": "running",
  "currentStep": "writing",
  "progress": 60,
  "attempt": 2,
  "result": null
}
POST/v1/generate/cancel

Cancel Generation

Cancel an in-progress generation. Reserved credits are refunded.

Parameters

ParameterTypeRequiredDescription
runIdstringYesThe run ID to cancel
Request Body
{ "runId": "550e8400-..." }
Response
{
  "status": "cancelled",
  "creditsRefunded": 30000
}
GET/v1/credits

Get Credit Balance

Get your current credit balance, plan details, and per-quality pricing.

Response
{
  "balance": 270000,
  "plan": "pro",
  "pricing": {
    "premium": 30,
    "standard": 20,
    "economy": 10
  }
}
GET/v1/posts

List Posts

Retrieve a paginated list of all generated posts with their status and metadata.

Parameters

ParameterTypeRequiredDescription
limitnumberNoResults per page (default: 20, max: 100)
offsetnumberNoPagination offset
GET/v1/posts/{id}

Get Post

Retrieve the full content and details of a specific post.

PATCH/v1/posts/{id}

Update Post

Update a post (e.g., change status to published).

DELETE/v1/posts/{id}

Delete Post

Permanently delete a post.

Base URL

https://www.scribepilot.ai/api

Legacy Field Aliases

For backward compatibility, the generate endpoint also accepts these legacy fields:

  • style → mapped to tone
  • length ("short" | "medium" | "long") → mapped to targetWordCount (800 / 1500 / 2500)