API Documentation

The Inkpolish API lets you score, rewrite, and generate guideline-aligned content programmatically — the same three tools available in your Inkpolish dashboard, connected directly to your own systems.

Base URL

https://inkpolish.com/api/v1

All requests must be made over HTTPS. Requests to plain HTTP will fail.

Who this is for

The Inkpolish API is available to these Inkpolish accounts:

Your account type decides only where the credits come from and a few response fields (see Credits & Usage). Every endpoint, request, and rate limit works the same way for everyone.

If your Individual subscription ends, your tokens stay in place. The three action endpoints (/check, /rewrite, /prompt) return 403 subscription_required until you subscribe again, while the read-only endpoints (balance, transactions, history) keep working.

Quick Start

1. Create your API token from your Inkpolish dashboard (see Authentication below).

2. Make your first request — check your available credits:

   curl https://inkpolish.com/api/v1/balance \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json"
   

3. Run a Score Check:

   curl -X POST https://inkpolish.com/api/v1/check \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"content": "Your article text here - at least 50 characters long."}'
   

That’s it — you’re connected.

Authentication

Every request to the Inkpolish API requires a personal API token, sent as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

We also recommend sending Accept: application/json on every request. Every response — including every error — is JSON.

Requests without a valid token, or using a revoked token, receive a 401 Unauthorized response.

Creating a token

API tokens are created directly from your Inkpolish account — there’s no separate developer portal or application process.

1. Log in to your Inkpolish account.
2. Click the Account icon in the bottom-left of your dashboard sidebar.
3. Scroll to the API Access section. (If you haven’t completed your billing details yet, finish that step first — the section appears right after.)
4. Click Create Token.
5. Give your token a clear, descriptive name — something that tells you what’s using it later, e.g. Zapier Integration or Internal Reporting Dashboard.
6. Your token is shown once, immediately after creation. Copy it and store it securely right away — Inkpolish stores only a hashed version internally and cannot display the plaintext token again after this point, for the same reason your password isn’t recoverable in plaintext either.

If you lose a token, don’t worry — just create a new one and revoke the old one from the same screen.

Revoking a token

From the same API Access section, click Revoke next to any token you want to disable. Revocation is immediate — anything actively using that token loses access right away. This can’t be undone; if you need access again, create a new token.

One important note on scope

A token authenticates as your account — it isn’t a separate, independent identity with its own credit allowance. Every request made with any of your tokens draws from the same credits as your dashboard usage. Creating multiple tokens (one per integration, for example) is useful for keeping track of what’s calling the API and for revoking access to one system without affecting another, but it doesn’t multiply or separate your available credits.

Rate Limits

If you exceed a limit, you’ll receive a 429 Too Many Requests response. The standard X-RateLimit-Limit and X-RateLimit-Remaining headers are included on every response, and a 429 response also includes Retry-After (in seconds), so you can build retry logic without guessing.

Credits & Usage

Every API call that generates content uses credits, at the exact same rate as using the tool directly in your dashboard — the same for every account type:

Read-only endpoints (balance, transactions, and the history/detail lookups) never use credits, regardless of how often you call them — only within the rate limits above.

Where your credits come from

Inkpolish has two credit models. Your account type decides which one you’re on:

• Subscription credits (Individual accounts). Your subscription includes 100 credits every month (on monthly and yearly plans alike), shared between your dashboard and the API. The allowance resets at the start of each monthly credit cycle. Unused credits don’t carry over, and there are no separate top-ups.
• Credit balance (Affiliate accounts). An ongoing balance with no cycle, made up of the credits Inkpolish grants to your affiliate account. They never expire and are reported as purchased_credits (even though you don’t pay for them). The balance also includes promotional_credits and promotional_expires_at fields, which are always 0 and null on an affiliate account.

Because the two models are different, the credits_remaining block (returned by every action endpoint), /balance, and /transactions each have one shape per credit model. Both shapes are documented below — check the fields to see which one you’re receiving.

Subscription credits (Individual) — credits_remaining

"credits_remaining": {
  "credits": 100,
  "credits_used": 41,
  "credits_remaining": 59,
  "cycle_end": "2026-10-29"
}

Credit balance (Affiliate) — credits_remaining

"credits_remaining": {
  "promotional_credits": 0,
  "purchased_credits": 238,
  "total_credits": 238
}

Endpoints

Actions

These three endpoints generate content and use credits. All are POST requests.

Account

Read-only, no credit cost.

History

Read-only, no credit cost. Look up past results from the three Actions endpoints above.

History covers everything you’ve run on your account — from the dashboard and from the API alike.

Request & Response Details

In the examples below, credits_remaining is shown in the subscription-credits shape (Individual accounts). Affiliate accounts receive the credit-balance shape instead (see Credits & Usage).

POST /check

Scores raw text content. Note: this endpoint accepts text content only — submitting a URL for Inkpolish to fetch and score isn’t currently supported via the API.

Request body

Success response — 201 Created

{
  "data": {
    "id": 123,
    "input_type": "text",
    "content_snippet": "The first 200 characters of your content…",
    "score": 78,
    "created_at": "2026-08-15T10:00:00.000000Z",
    "source_url": null,
    "category_scores": { "...": "guideline category breakdown" },
    "fixes": ["..."]
  },
  "credits_remaining": {
    "credits": 100,
    "credits_used": 42,
    "credits_remaining": 58,
    "cycle_end": "2026-10-29"
  }
}

POST /rewrite

Rewrites text content, optionally guided by specific issues to address.

Request body

Like /check, this endpoint accepts text content only, not a URL.

Success response — 201 Created

{
  "data": {
    "id": 456,
    "rewritten_content": "…",
    "fixes_applied": ["..."],
    "guideline_alignment": "...",
    "created_at": "2026-08-15T10:00:00.000000Z"
  },
  "credits_remaining": {
    "credits": 100,
    "credits_used": 44,
    "credits_remaining": 56,
    "cycle_end": "2026-10-29"
  }
}

POST /prompt

Generates a guideline-aligned prompt for content you haven’t written yet.

Request body

Success response — 201 Created

{
  "data": {
    "id": 789,
    "generated_prompt": "…",
    "created_at": "2026-08-15T10:00:00.000000Z"
  },
  "credits_remaining": {
    "credits": 100,
    "credits_used": 45,
    "credits_remaining": 55,
    "cycle_end": "2026-10-29"
  }
}

GET /balance

Success response — 200 OK

Subscription credits (Individual accounts):

{
  "data": {
    "credits": 100,
    "credits_used": 41,
    "credits_remaining": 59,
    "cycle_start": "2026-09-29",
    "cycle_end": "2026-10-29"
  }
}

If there’s no active credit cycle, the counts are 0 and both dates are null.

Credit balance (Affiliate accounts):

{
  "data": {
    "promotional_credits": 0,
    "purchased_credits": 64,
    "total_credits": 64,
    "promotional_expires_at": null
  }
}

GET /transactions

Paginated (see Pagination). Accepts an optional ?per_page= parameter (default 25, capped at 100). Newest first.

Subscription credits (Individual accounts) — a usage history of every Score Check, Rewrite, and Prompt you’ve run, from the dashboard or the API. Each record:

Your one free Score Check (the one available before subscribing) never used a credit, so it isn’t listed here.

Credit balance (Affiliate accounts) — a full credit ledger: every grant to your account and every action that used credits. Each record:

GET /checks, GET /rewrites, GET /prompts

All three are paginated (see Pagination), newest first, and accept an optional ?per_page= parameter (default 25, capped at 100).

List responses return a summary of each record. The full content is only included when you fetch that specific record by ID via the matching detail endpoint (GET /checks/{id}, GET /rewrites/{id}, GET /prompts/{id}), which returns it inside data.

Records created from your dashboard can have input_type url with a source_url. Records created through the API are always text.

Pagination

Every list endpoint (/transactions, /checks, /rewrites, /prompts) uses the same pagination format. The records are in data, alongside these fields:

Request a page with ?page=2 (and optionally ?per_page=).

Errors

Every error response is JSON with an error code and a human-readable message:

{
  "error": "insufficient_credit",
  "message": "You don't have enough credits to complete this action. Your credits refresh on 2026-10-29."
}

A validation_failed response also lists the problem per field in errors:

{
  "error": "validation_failed",
  "message": "The content field must be at least 50 characters.",
  "errors": {
    "content": ["The content field must be at least 50 characters."]
  }
}

Insufficient credits

Action endpoints (/check, /rewrite, /prompt) check your credits before running, against that action’s full cost — you’re never charged for a request that couldn’t complete. If you don’t have enough (for example, 1 credit left and a 2-credit rewrite), you’ll get a 402 with your current credits attached, in your credit model’s shape.

The message tells you what to do next, depending on your account:

Example (Individual):

{
  "error": "insufficient_credit",
  "message": "You don't have enough credits to complete this action. Your credits refresh on 2026-10-29.",
  "credits_remaining": {
    "credits": 100,
    "credits_used": 99,
    "credits_remaining": 1,
    "cycle_end": "2026-10-29"
  }
}

Support

Questions, feedback, or something not working as documented? Email hello@inkpolish.com — a real person reads every message.

For questions about your Inkpolish account, billing, or credits specifically, the fastest answer is usually in your dashboard directly.