API Documentation

Welcome to the InkWell API. This guide covers everything you need to integrate with our publishing platform. All requests should be made over HTTPS. Calls made over plain HTTP will fail.

⚠️

Base URL: All API endpoints are relative to https://api.inkwell.io/v1

Authentication

InkWell uses API keys to authenticate requests. You can view and manage your API keys in your dashboard. Include your key in the Authorization header as a Bearer token.

Request Header Authorization: Bearer <YOUR_API_KEY>

⚠️

Never expose your API keys in client-side code or public repositories. They grant full access to your account.

Rate Limits

The API is rate-limited to ensure fair usage. Limits are applied per API key:

Plan	Requests / Minute	Burst
Free	60	10
Pro	300	50
Enterprise	Custom	Custom

When you exceed the rate limit, you will receive a 429 Too Many Requests response. The X-RateLimit-Remaining header indicates how many requests you have left.

Endpoints

GET /posts List all published posts

Retrieves a paginated list of posts. Supports filtering by category, author, and date range.

Query Parameters

Parameter	Type	Description
limit	integer	Number of results (1-100). Default: 20
offset	integer	Pagination offset. Default: 0
category	string	Filter by category slug
author_id	string	Filter by author UUID

Example Response

200 OK { "data": [ { "id": "pst_8x7k9m2n", "title": "Building Scalable Blog APIs", "slug": "building-scalable-blog-apis", "excerpt": "How we architected InkWell to handle 10k+ requests...", "published_at": "2024-12-15T10:00:00Z", "read_time": 6, "author": { "id": "usr_1a2b3c", "name": "Sarah Kim" } } ], "meta": { "total": 128, "has_more": true } }

POST /posts Create a new post

Creates a new draft post. Requires write permissions.

Request Body (JSON)

Field	Type	Description
title required	string	Post title (max 100 chars)
content required	string	Markdown or HTML content
category	string	Category slug
tags	array	Array of tag strings
publish	boolean	Set to true to publish immediately

Example Request

POST Body { "title": "My First InkWell Post", "content": "# Hello World\n\nThis is a test post...", "category": "technology", "tags": ["api", "tutorial"], "publish": false }

GET /posts/:slug Get post by slug

Fetches a single post by its URL slug. Returns full content, metadata, and comments.

200 OK { "id": "pst_8x7k9m2n", "slug": "building-scalable-blog-apis", "title": "Building Scalable Blog APIs", "content": "Full markdown content here...", "published_at": "2024-12-15T10:00:00Z", "views": 4521, "likes": 189 }

PUT /posts/:slug Update a post

Updates an existing post. Only fields provided in the payload will be modified (partial update).

Returns the updated post object on success.

DELETE /posts/:slug Delete a post

Permanently deletes a post. This action cannot be undone. Returns 204 No Content on success.

Error Handling

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

Code	Meaning	Description
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions for this action
404	Not Found	Resource does not exist
429	Rate Limit	Too many requests, slow down
500	Server Error	Something went wrong on our end

Error Response Format

4xx/5xx Response { "error": { "code": "validation_failed", "message": "The 'title' field is required and must not exceed 100 characters.", "details": { "title": ["value.too_long"] } } }

SDKs & Tools

We provide official SDKs to make integration easier:

Language	Package	Repository
JavaScript/TypeScript	`@inkwell/api-client`	GitHub
Python	`inkwell-python`	GitHub
Go	`github.com/inkwell/go-sdk`	GitHub
cURL	Built-in	Examples