WebInk API Documentation

Introduction

The WebInk API provides a powerful solution for converting web content to Markdown format with customizable output. Whether you're building a content aggregation application or creating a personal knowledge base, the WebInk API offers robust support for your needs.

API Overview

• The API supports both GET and POST request methods.
• It uses content negotiation to determine the format of the returned data.
• You can specify the desired response type by setting the Accept header.

Supported Accept Types

• application/json: Returns the complete MarkdownContent
• text/markdown: Returns only the Markdown text

If no Accept header is specified, the API defaults to returning the complete MarkdownContent in JSON format.

MarkdownContent Structure

export interface MarkdownContent {
    url: string;
    title: string;
    content: string;
    markdown: string;
    length?: number;
    excerpt?: string;
    byline?: string;
    dir?: string;
    siteName?: string;
    lang?: string;
    publishedTime?: string;
}

API Endpoints

GET /api/markdown

Use this endpoint for simple requests without additional options.

Retrieve Complete MarkdownContent:

curl -H "Accept: application/json" "https://webink.app/api/markdown?url=https://example.com"

Retrieve Markdown Only:

curl -H "Accept: text/markdown" "https://webink.app/api/markdown?url=https://example.com"

POST /api/markdown

Use this endpoint when you need to specify templates or transformation options.

Request Headers

• Accept: application/json or Accept: text/markdown
• Content-Type: application/json

Request Body Parameters

• url: Required, the URL of the webpage to convert
• template: Optional, a template string for customizing the output format
• transformOptions: Optional, for customizing Markdown conversion options

Example: Retrieve Content Using a Template

curl -X POST https://webink.app/api/markdown \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "template": "{{title}} - {{url}}"
  }'

Example: Request with Transformation Options

curl -X POST https://webink.app/api/markdown \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "template": "{{title}} - {{url}}",
    "transformOptions": {
      "headingStyle": "atx",
      "bulletListMarker": "-"
    }
  }'

Supported transformOptions

• headingStyle: Heading style, either 'setext' or 'atx'
• hr: Markdown representation of horizontal rules
• bulletListMarker: Unordered list marker, either '-', '*', or '+'
• codeBlockStyle: Code block style, either 'indented' or 'fenced'
• emDelimiter: Emphasis delimiter, either '_' or '*'
• fence: Code block fence characters
• strongDelimiter: Strong emphasis delimiter, either '**' or '__'

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests:

• 200 OK: Successful request
• 400 Bad Request: Invalid request body
• 404 Not Found: Content cannot be retrieved
• 405 Method Not Allowed: Unsupported HTTP method

Additional Information

1. The API uses Edge Runtime for faster response times.
2. Response headers include Cache-Control: public, max-age=7200, allowing results to be cached for 24 hours.

Conclusion

The WebInk API offers a flexible and powerful way to convert web content to Markdown. By supporting both GET and POST methods, along with customizable templates and transformation options, it caters to a wide range of use cases and integration scenarios.