API Documentation

The Publish Markdown API provides simple REST endpoints to create, read, update, and delete markdown documents. All requests require authentication via API key and return JSON responses.

Base URL

All API requests should be made to:

https://publishmarkdown.com/v1/api

Request & Authentication

All requests must be sent over HTTPS with any payload formatted in JSON (application/json). Every request must include the headers content-type: application/json and api-key.

curl -X POST 'https://publishmarkdown.com/v1/api/{endpoint}'
     -H 'content-type: application/json'
     -H 'api-key: {YOUR_API_KEY}'
     -d '{"data":"john@doe.com"}'

How to Generate an API Key

1. Go to your dashboard (you need to be logged in) and click on API Keys button on the sidebar.

2. In the API Keys modal, enter a name for your new key and click Create API Key.

3. Copy your new API key and keep it safe. You will use this key in your API requests.

Note: API keys are scoped to individual users. You can only access and modify your own markdowns.

Response

The API uses conventional HTTP response codes and returns JSON responses.

Code	Description
200	Success
400	Bad Request (missing/invalid parameters)
401	Unauthorized (invalid API key or insufficient permissions)
404	Not Found
500	Internal Server Error

Response Format

// 4xx or 5xx error
{
  "status": "error",
  "message": "detailed error message",
  "data": {}
}

// 200 success
{
  "status": "success",
  "message": "success message",
  "data": {
    "items": [
      {
        "id": "doc_12345",
        "identifier": "my-article",
        "content": "# Hello World\nThis is markdown.",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "views": 42,
        "expiredAt": null,
        "userType": "api"
      }
    ],
    "limit": 10,
    "offset": 0,
    "totalData": 1
  }
}
}

Get All Markdown

GET

Retrieve a paginated list of your markdown documents.

Endpoint

GET /markdown

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Number of items to return (max 50)
offset	integer	0	Number of items to skip

Example Request

curl "https://publishmarkdown.com/v1/api/markdown?limit=10&offset=0"
     -H "api-key: {YOUR_API_KEY}"
     -H "Content-Type: application/json"

Example Response | 200 Success

{
  "status": "success",
  "message": "markdown fetched successfully",
  "data": {
    "items": [
      {
        "identifier": "my-article",
        "content": "# Hello World",
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T10:30:00Z",
        "expiredAt": "2025-01-15T10:30:00Z"
        "is_password_protected": false
      }
    ],
    "limit": 10,
    "offset": 0,
    "totalData": 1
  }
}

Example Response | 500 Error

{
  "status": "error",
  "message": "internal server error",
  "data": {}
}

Get Markdown by Identifier

GET

Retrieve a specific markdown by its identifier.

Endpoint

GET /markdown/{IDENTIFIER}

Path Parameters

Parameter	Type	Description
IDENTIFIER	string	Markdown identifier

Example Request

curl "https://publishmarkdown.com/v1/api/markdown/{IDENTIFIER}" 
     -H "api-key: {YOUR_API_KEY}"
     -H "Content-Type: application/json"

Example Response | 200 Success

{
  "status": "success",
  "message": "markdown fetched successfully",
  "data": {
    "identifier": "my-article",
    "content": "# Hello World",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "expiredAt": "2026-01-01T12:00:00Z",
    "is_password_protected": false
  }
}

Example Response | 404 Error

{
  "status": "error",
  "message": "markdown not found",
  "data": {}
}

Create Markdown

POST

Create a new markdown document.

Endpoint

POST /markdown

Request Body

Field	Type	Required	Description
content	string	Yes	Markdown content
identifier	string	No	Custom URL identifier, will be random if not provided
password	string	No	Password protection (plain text)
expiredAt	string	No	Expiration date (ISO 8601 format with UTC timezone)

Example Request

curl -X POST "https://publishmarkdown.com/v1/api/markdown"
     -H "api-key: {YOUR_API_KEY}"
     -H "Content-Type: application/json"
     -d '{
        "identifier": "my-article",
        "content": "# Hello World",
        "password": "secret123",
        "expiredAt": "2026-01-01T12:00:00Z"
      }'

Example Response | 200 Success

{
  "status": "success",
  "message": "markdown created successfully",
  "data": {
    "identifier": "my-article",
    "url": "https://publishmarkdown.com/my-article"
  }
}

Example Response | 400 Error

{
  "status": "error",
  "message": "content is empty, please check your request",
  "data": {}
}

Example Response | 500 Error

{
  "status": "error",
  "message": "internal server error",
  "data": {}
}

Edit Markdown by Identifier

PUT

Edit an existing markdown. This will only edit the provided fields from the request body.

Endpoint

PUT /markdown/{IDENTIFIER}

Path Parameters

Parameter	Type	Description
IDENTIFIER	string	Markdown identifier

Request Body

Field	Type	Required	Description
content	string	No	Updated markdown content
identifier	string	No	New identifier
password	string	No	Updated password
expiredAt	string	No	Updated expiration date

Example Request

curl -X PUT "https://publishmarkdown.com/v1/api/markdown/{IDENTIFIER}"
     -H "api-key: {YOUR_API_KEY}"
     -H "Content-Type: application/json"
     -d '{
        "content": "# Updated Title",
        "identifier": "updated-article"
      }'

Example Response | 200 Success

{
  "status": "success",
  "message": "markdown updated successfully",
  "data": {
    "identifier": "updated-article",
    "url": "https://publishmarkdown.com/updated-article"
  }
}

Example Response | 404 Error

{
  "status": "error",
  "message": "markdown not found",
  "data": {}
}

Example Response | 500 Error

{
  "status": "error",
  "message": "internal server error",
  "data": {}
}

Delete Markdown by Identifier

DELETE

Delete a markdown permanently.

Endpoint

DELETE /markdown/{IDENTIFIER}

Path Parameters

Parameter	Type	Description
IDENTIFIER	string	Markdown identifier to delete

Example Request

curl -X DELETE "https://publishmarkdown.com/v1/api/markdown/{IDENTIFIER}"
     -H "api-key: {YOUR_API_KEY}"

Example Response | 200 Success

{
  "status": "success",
  "message": "markdown deleted successfully",
  "data": {}
}

Example Response | 404 Error

{
  "status": "error",
  "message": "markdown not found",
  "data": {}
}

Example Response | 500 Error

{
  "status": "error",
  "message": "internal server error",
  "data": {}
}