API Documentation

Programmatically interact with InkWell's content publishing platform. Create, read, update, and manage articles, users, and analytics through our RESTful API.

ℹ️

Base URL:
All API requests should be made to https://api.inkwell.com/v1

Quick Start

Generate your API key from the Developer Dashboard. Include it in the Authorization header as a Bearer token. Our API uses standard HTTP methods and returns JSON responses.

Authentication

InkWell uses API keys to authenticate requests. You can view and manage your API keys in the developer portal. API keys carry many privileges, so be sure to keep them secure.

HTTP Header

Authorization: Bearer sk_live_51Hz9K2eZv8xQm7pL3nR4wY

⚠️

Do not expose your secret API keys in client-side code or public repositories. Use environment variables to store them securely.

Articles

The Articles API allows you to create, retrieve, update, and delete blog posts. Articles support rich text content, categories, tags, and author assignments.

List Articles

GET /v1/articles

Retrieve a paginated list of published articles. Results can be filtered by category, author, or publication date.

Query Parameters

Name	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (max: 100)
category	string	No	Filter by category slug
status	enum	No	published, draft, archived

Example Request

cURL

curl -X GET "https://api.inkwell.com/v1/articles?page=1&limit=10&category=technology" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

JSON

{
  "data": [
    {
      "id": "art_938472",
      "title": "The Future of Generative AI in Content Creation",
      "slug": "future-of-generative-ai",
      "status": "published",
      "author": { "id": "usr_12", "name": "Sarah Kim" },
      "published_at": "2024-12-15T10:00:00Z",
      "read_time_minutes": 8
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 42,
    "total_items": 418,
    "per_page": 10
  }
}

Create Article

POST /v1/articles

Publish a new article to your InkWell workspace. Supports markdown or HTML content.

Request Body

Name	Type	Required	Description
title	string	Yes	Article headline (max 100 chars)
content	string	Yes	Markdown or HTML body content
category	string	Yes	Category slug
tags	array	No	List of tag strings
status	enum	No	draft or published (default: draft)

Example Request

JSON

{
  "title": "Building Scalable Web Apps with Next.js 14",
  "content": "# Introduction\n\nNext.js 14 introduces groundbreaking features...",
  "category": "technology",
  "tags": ["react", "nextjs", "web-dev"],
  "status": "draft"
}

Error Handling

InkWell uses standard HTTP status codes to indicate the success or failure of requests. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Code	Meaning
200	OK - Request succeeded
201	Created - Resource created successfully
400	Bad Request - Invalid payload or parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

JSON

{
  "error": {
    "code": 401,
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "request_id": "req_7f8d9e2a1b"
  }
}

Rate Limits

To ensure platform stability, API requests are limited based on your subscription tier:

🟢 Free Tier: 100 requests/hour
🔵 Pro Tier: 1,000 requests/hour
🟣 Enterprise: Custom limits

Rate limit headers are included in every response:

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 942
X-RateLimit-Reset: 1702656000

Pagination

All list endpoints return paginated results. Use the page and limit query parameters to navigate through results. The response includes a pagination object with metadata for building UI controls.