> ## Documentation Index
> Fetch the complete documentation index at: https://docs.directify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Articles

> Manage blog articles through the Directify API - create, read, update, and delete articles with full CRUD operations and SEO support.

## Articles

In Directify, **articles** are blog posts that appear in your directory's blog section. These can be written in HTML or Markdown format and include full SEO metadata support. The API uses slug-based storage to prevent duplicate articles and automatically generates SEO-friendly URLs.

### Get Directory Articles

Retrieve all articles for a specific directory with pagination.

```http theme={null}
GET /api/directories/{directory_id}/articles
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory

**Query Parameters:**

* `page` (integer, optional): Page number for pagination (default: 1)

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "title": "Getting Started with React",
      "slug": "getting-started-with-react",
      "content": "<h1>Getting Started with React</h1><p>React is a powerful JavaScript library...</p>",
      "markdown": "# Getting Started with React\n\nReact is a powerful JavaScript library...",
      "is_markdown": true,
      "active": true,
      "published_at": "2024-01-15T10:30:00.000000Z",
      "thumbnail_url": "https://example.com/images/react-tutorial.jpg",
      "thumbnail_alt_text": "React tutorial screenshot",
      "categories": ["tutorial", "react", "frontend"],
      "blog_buster_article_id": null,
      "seo": {
        "id": 1,
        "title": "Getting Started with React - Complete Tutorial",
        "description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
        "keywords": "react, tutorial, javascript, frontend",
        "og_title": "Getting Started with React - Complete Tutorial",
        "og_description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
        "og_image": "https://example.com/images/react-tutorial-og.jpg",
        "twitter_title": "Getting Started with React - Complete Tutorial",
        "twitter_description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
        "twitter_image": "https://example.com/images/react-tutorial-twitter.jpg",
        "canonical": "https://your-directify-domain.com/blog/getting-started-with-react/",
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      },
      "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "created_at": "2024-01-01T00:00:00.000000Z",
        "updated_at": "2024-01-01T00:00:00.000000Z"
      },
      "directory": {
        "id": 1,
        "name": "My Directory",
        "slug": "my-directory",
        "domain": "my-directory.com",
        "created_at": "2024-01-01T00:00:00.000000Z",
        "updated_at": "2024-01-01T00:00:00.000000Z"
      },
      "article_url": "https://my-directory.com/blog/getting-started-with-react/",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://your-directify-domain.com/api/directories/1/articles?page=1",
    "last": "https://your-directify-domain.com/api/directories/1/articles?page=3",
    "prev": null,
    "next": "https://your-directify-domain.com/api/directories/1/articles?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "per_page": 100,
    "to": 100,
    "total": 250
  }
}
```

### Get Single Article

Retrieve a specific article by ID.

```http theme={null}
GET /api/directories/{directory_id}/articles/{article_id}
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory
* `article_id` (integer, required): The ID of the article

**Response:**

```json theme={null}
{
  "data": {
    "id": 1,
    "title": "Getting Started with React",
    "slug": "getting-started-with-react",
    "content": "<h1>Getting Started with React</h1><p>React is a powerful JavaScript library...</p>",
    "markdown": "# Getting Started with React\n\nReact is a powerful JavaScript library...",
    "is_markdown": true,
    "active": true,
    "published_at": "2024-01-15T10:30:00.000000Z",
    "thumbnail_url": "https://example.com/images/react-tutorial.jpg",
    "thumbnail_alt_text": "React tutorial screenshot",
    "categories": ["tutorial", "react", "frontend"],
    "blog_buster_article_id": null,
    "seo": {
      "id": 1,
      "title": "Getting Started with React - Complete Tutorial",
      "description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
      "keywords": "react, tutorial, javascript, frontend",
      "og_title": "Getting Started with React - Complete Tutorial",
      "og_description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
      "og_image": "https://example.com/images/react-tutorial-og.jpg",
      "twitter_title": "Getting Started with React - Complete Tutorial",
      "twitter_description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
      "twitter_image": "https://example.com/images/react-tutorial-twitter.jpg",
      "canonical": "https://your-directify-domain.com/blog/getting-started-with-react/",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    },
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "directory": {
      "id": 1,
      "name": "My Directory",
      "slug": "my-directory",
      "domain": "my-directory.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "article_url": "https://my-directory.com/blog/getting-started-with-react/",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}
```

### Check Article Exists

Check if an article with a specific slug already exists in the directory.

```http theme={null}
POST /api/directories/{directory_id}/articles/exists
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory

**Request Body:**

```json theme={null}
{
  "slug": "getting-started-with-react"
}
```

**Request Body Fields:**

* `slug` (string, required): The article slug to check for existence

**Response (Article exists):**

```json theme={null}
{
  "message": "Article already exists in this directory"
}
```

**Response (Article doesn't exist):**

```json theme={null}
{
  "message": "Article does not exist in this directory"
}
```

### Create Article

Create a new article in the directory. The API uses `updateOrCreate` based on slug to prevent duplicates.

```http theme={null}
POST /api/directories/{directory_id}/articles
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory

**Request Body:**

```json theme={null}
{
  "title": "Advanced React Patterns",
  "slug": "advanced-react-patterns",
  "content": "<h1>Advanced React Patterns</h1><p>Learn advanced patterns in React...</p>",
  "markdown": "# Advanced React Patterns\n\nLearn advanced patterns in React...",
  "active": true,
  "published_at": "2024-01-20T14:00:00.000000Z",
  "thumbnail_url": "https://example.com/images/advanced-react.jpg",
  "thumbnail_alt_text": "Advanced React patterns illustration",
  "categories": ["advanced", "react", "patterns"],
  "seo": {
    "title": "Advanced React Patterns - Complete Guide",
    "description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
    "keywords": "react, patterns, advanced, hooks, hocs",
    "og_title": "Advanced React Patterns - Complete Guide",
    "og_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
    "og_image": "https://example.com/images/advanced-react-og.jpg",
    "twitter_title": "Advanced React Patterns - Complete Guide",
    "twitter_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
    "twitter_image": "https://example.com/images/advanced-react-twitter.jpg",
    "canonical": "https://your-directify-domain.com/blog/advanced-react-patterns/"
  }
}
```

**Request Body Fields:**

* `title` (string, required): The article title (max 255 characters)
* `slug` (string, optional): URL-safe slug (lowercase letters, numbers, hyphens only). Auto-generated from title if not provided
* `content` (string, optional): HTML content of the article. Required if `markdown` is not provided
* `markdown` (string, optional): Markdown content of the article. Required if `content` is not provided
* `active` (boolean, optional): Whether the article is published (default: true)
* `published_at` (datetime, optional): Publication date (default: current timestamp)
* `thumbnail_url` (string, optional): URL to the article thumbnail image (max 255 characters)
* `thumbnail_alt_text` (string, optional): Alt text for the thumbnail image (max 255 characters)
* `categories` (array, optional): Array of category strings for organizing articles
* `seo` (object, optional): SEO metadata object with the following optional fields:
  * `title` (string, optional): SEO title (max 255 characters)
  * `description` (string, optional): Meta description (max 500 characters)
  * `keywords` (string, optional): Meta keywords (max 255 characters)
  * `og_title` (string, optional): Open Graph title (max 255 characters)
  * `og_description` (string, optional): Open Graph description (max 500 characters)
  * `og_image` (string, optional): Open Graph image URL (max 255 characters)
  * `twitter_title` (string, optional): Twitter card title (max 255 characters)
  * `twitter_description` (string, optional): Twitter card description (max 500 characters)
  * `twitter_image` (string, optional): Twitter card image URL (max 255 characters)
  * `canonical` (string, optional): Canonical URL (max 255 characters). Leave empty to use the article's own URL

**Response:**

```json theme={null}
{
  "data": {
    "id": 2,
    "title": "Advanced React Patterns",
    "slug": "advanced-react-patterns",
    "content": "<h1>Advanced React Patterns</h1><p>Learn advanced patterns in React...</p>",
    "markdown": "# Advanced React Patterns\n\nLearn advanced patterns in React...",
    "is_markdown": true,
    "active": true,
    "published_at": "2024-01-20T14:00:00.000000Z",
    "thumbnail_url": "https://example.com/images/advanced-react.jpg",
    "thumbnail_alt_text": "Advanced React patterns illustration",
    "categories": ["advanced", "react", "patterns"],
    "blog_buster_article_id": null,
    "seo": {
      "id": 2,
      "title": "Advanced React Patterns - Complete Guide",
      "description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
      "keywords": "react, patterns, advanced, hooks, hocs",
      "og_title": "Advanced React Patterns - Complete Guide",
      "og_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
      "og_image": "https://example.com/images/advanced-react-og.jpg",
      "twitter_title": "Advanced React Patterns - Complete Guide",
      "twitter_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
      "twitter_image": "https://example.com/images/advanced-react-twitter.jpg",
      "canonical": "https://your-directify-domain.com/blog/advanced-react-patterns/",
      "created_at": "2024-01-20T14:00:00.000000Z",
      "updated_at": "2024-01-20T14:00:00.000000Z"
    },
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "directory": {
      "id": 1,
      "name": "My Directory",
      "slug": "my-directory",
      "domain": "my-directory.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "article_url": "https://my-directory.com/blog/advanced-react-patterns/",
    "created_at": "2024-01-20T14:00:00.000000Z",
    "updated_at": "2024-01-20T14:00:00.000000Z"
  }
}
```

### Update Article

Update an existing article. If the title changes and no slug is provided, a new slug will be automatically generated.

```http theme={null}
PUT /api/directories/{directory_id}/articles/{article_id}
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory
* `article_id` (integer, required): The ID of the article

**Request Body:**

```json theme={null}
{
  "title": "Updated: Advanced React Patterns",
  "content": "<h1>Updated: Advanced React Patterns</h1><p>Updated content with new information...</p>",
  "markdown": "# Updated: Advanced React Patterns\n\nUpdated content with new information...",
  "active": true,
  "categories": ["updated", "react", "patterns", "tutorial"],
  "seo": {
    "title": "Updated: Advanced React Patterns - Complete Guide 2024",
    "description": "Master advanced React patterns with the latest updates and best practices for 2024.",
    "keywords": "react, patterns, advanced, hooks, hocs, 2024"
  }
}
```

**Request Body Fields:**

* `title` (string, optional): The article title (max 255 characters)
* `slug` (string, optional): URL-safe slug (lowercase letters, numbers, hyphens only). Auto-generated from title if title changes and no slug provided
* `content` (string, optional): HTML content of the article. Required if `markdown` is not provided
* `markdown` (string, optional): Markdown content of the article. Required if `content` is not provided
* `active` (boolean, optional): Whether the article is published
* `published_at` (datetime, optional): Publication date
* `thumbnail_url` (string, optional): URL to the article thumbnail image (max 255 characters)
* `thumbnail_alt_text` (string, optional): Alt text for the thumbnail image (max 255 characters)
* `categories` (array, optional): Array of category strings for organizing articles
* `seo` (object, optional): SEO metadata object with the following optional fields:
  * `title` (string, optional): SEO title (max 255 characters)
  * `description` (string, optional): Meta description (max 500 characters)
  * `keywords` (string, optional): Meta keywords (max 255 characters)
  * `og_title` (string, optional): Open Graph title (max 255 characters)
  * `og_description` (string, optional): Open Graph description (max 500 characters)
  * `og_image` (string, optional): Open Graph image URL (max 255 characters)
  * `twitter_title` (string, optional): Twitter card title (max 255 characters)
  * `twitter_description` (string, optional): Twitter card description (max 500 characters)
  * `twitter_image` (string, optional): Twitter card image URL (max 255 characters)
  * `canonical` (string, optional): Canonical URL (max 255 characters). Leave empty to use the article's own URL

**Response:**

```json theme={null}
{
  "data": {
    "id": 2,
    "title": "Updated: Advanced React Patterns",
    "slug": "updated-advanced-react-patterns",
    "content": "<h1>Updated: Advanced React Patterns</h1><p>Updated content with new information...</p>",
    "markdown": "# Updated: Advanced React Patterns\n\nUpdated content with new information...",
    "is_markdown": true,
    "active": true,
    "published_at": "2024-01-20T14:00:00.000000Z",
    "thumbnail_url": "https://example.com/images/advanced-react.jpg",
    "thumbnail_alt_text": "Advanced React patterns illustration",
    "categories": ["updated", "react", "patterns", "tutorial"],
    "blog_buster_article_id": null,
    "seo": {
      "id": 2,
      "title": "Updated: Advanced React Patterns - Complete Guide 2024",
      "description": "Master advanced React patterns with the latest updates and best practices for 2024.",
      "keywords": "react, patterns, advanced, hooks, hocs, 2024",
      "og_title": "Advanced React Patterns - Complete Guide",
      "og_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
      "og_image": "https://example.com/images/advanced-react-og.jpg",
      "twitter_title": "Advanced React Patterns - Complete Guide",
      "twitter_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
      "twitter_image": "https://example.com/images/advanced-react-twitter.jpg",
      "canonical": "https://your-directify-domain.com/blog/advanced-react-patterns/",
      "created_at": "2024-01-20T14:00:00.000000Z",
      "updated_at": "2024-01-20T15:30:00.000000Z"
    },
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "directory": {
      "id": 1,
      "name": "My Directory",
      "slug": "my-directory",
      "domain": "my-directory.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "article_url": "https://my-directory.com/blog/updated-advanced-react-patterns/",
    "created_at": "2024-01-20T14:00:00.000000Z",
    "updated_at": "2024-01-20T15:30:00.000000Z"
  }
}
```

### Toggle Article Status

Toggle the active status of an article (publish/unpublish).

```http theme={null}
PATCH /api/directories/{directory_id}/articles/{article_id}/toggle
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory
* `article_id` (integer, required): The ID of the article

**Response:**

```json theme={null}
{
  "data": {
    "id": 2,
    "title": "Updated: Advanced React Patterns",
    "slug": "updated-advanced-react-patterns",
    "content": "<h1>Updated: Advanced React Patterns</h1><p>Updated content with new information...</p>",
    "markdown": "# Updated: Advanced React Patterns\n\nUpdated content with new information...",
    "is_markdown": true,
    "active": false,
    "published_at": "2024-01-20T14:00:00.000000Z",
    "thumbnail_url": "https://example.com/images/advanced-react.jpg",
    "thumbnail_alt_text": "Advanced React patterns illustration",
    "categories": ["updated", "react", "patterns", "tutorial"],
    "blog_buster_article_id": null,
    "seo": {
      "id": 2,
      "title": "Updated: Advanced React Patterns - Complete Guide 2024",
      "description": "Master advanced React patterns with the latest updates and best practices for 2024.",
      "keywords": "react, patterns, advanced, hooks, hocs, 2024",
      "og_title": "Advanced React Patterns - Complete Guide",
      "og_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
      "og_image": "https://example.com/images/advanced-react-og.jpg",
      "twitter_title": "Advanced React Patterns - Complete Guide",
      "twitter_description": "Master advanced React patterns including render props, higher-order components, and custom hooks.",
      "twitter_image": "https://example.com/images/advanced-react-twitter.jpg",
      "canonical": "https://your-directify-domain.com/blog/advanced-react-patterns/",
      "created_at": "2024-01-20T14:00:00.000000Z",
      "updated_at": "2024-01-20T15:30:00.000000Z"
    },
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "directory": {
      "id": 1,
      "name": "My Directory",
      "slug": "my-directory",
      "domain": "my-directory.com",
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    "article_url": "https://my-directory.com/blog/updated-advanced-react-patterns/",
    "created_at": "2024-01-20T14:00:00.000000Z",
    "updated_at": "2024-01-20T15:35:00.000000Z"
  }
}
```

### Get Articles by Category

Retrieve articles filtered by a specific category.

```http theme={null}
GET /api/directories/{directory_id}/articles/category/{category}
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory
* `category` (string, required): The category name to filter by

**Query Parameters:**

* `page` (integer, optional): Page number for pagination (default: 1)

**Response:**

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "title": "Getting Started with React",
      "slug": "getting-started-with-react",
      "content": "<h1>Getting Started with React</h1><p>React is a powerful JavaScript library...</p>",
      "markdown": "# Getting Started with React\n\nReact is a powerful JavaScript library...",
      "is_markdown": true,
      "active": true,
      "published_at": "2024-01-15T10:30:00.000000Z",
      "thumbnail_url": "https://example.com/images/react-tutorial.jpg",
      "thumbnail_alt_text": "React tutorial screenshot",
      "categories": ["tutorial", "react", "frontend"],
      "blog_buster_article_id": null,
      "seo": {
        "id": 1,
        "title": "Getting Started with React - Complete Tutorial",
        "description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
        "keywords": "react, tutorial, javascript, frontend",
        "og_title": "Getting Started with React - Complete Tutorial",
        "og_description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
        "og_image": "https://example.com/images/react-tutorial-og.jpg",
        "twitter_title": "Getting Started with React - Complete Tutorial",
        "twitter_description": "Learn React from scratch with this comprehensive tutorial covering components, hooks, and best practices.",
        "twitter_image": "https://example.com/images/react-tutorial-twitter.jpg",
        "canonical": "https://your-directify-domain.com/blog/getting-started-with-react/",
        "created_at": "2024-01-15T10:30:00.000000Z",
        "updated_at": "2024-01-15T10:30:00.000000Z"
      },
      "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "created_at": "2024-01-01T00:00:00.000000Z",
        "updated_at": "2024-01-01T00:00:00.000000Z"
      },
      "directory": {
        "id": 1,
        "name": "My Directory",
        "slug": "my-directory",
        "domain": "my-directory.com",
        "created_at": "2024-01-01T00:00:00.000000Z",
        "updated_at": "2024-01-01T00:00:00.000000Z"
      },
      "article_url": "https://my-directory.com/blog/getting-started-with-react/",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://your-directify-domain.com/api/directories/1/articles/category/tutorial?page=1",
    "last": "https://your-directify-domain.com/api/directories/1/articles/category/tutorial?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 100,
    "to": 1,
    "total": 1
  }
}
```

### Delete Article

Delete an article from the directory.

```http theme={null}
DELETE /api/directories/{directory_id}/articles/{article_id}
```

**Parameters:**

* `directory_id` (integer, required): The ID of the directory
* `article_id` (integer, required): The ID of the article

**Response:**

```json theme={null}
{
  "message": "Article deleted successfully"
}
```

## Key Features

### Slug-Based Storage

* Articles are stored using `updateOrCreate` based on slug to prevent duplicates
* Slugs are automatically generated from titles if not provided
* Slugs must be URL-safe (lowercase letters, numbers, and hyphens only)
* Slugs are unique within each directory

### Content Format Support

* Support for both HTML and Markdown content
* Use either `content` (HTML) or `markdown` field
* At least one content field is required (`required_without` validation)
* `is_markdown` flag indicates which format is being used

### SEO Integration

* Full SEO metadata support including Open Graph and Twitter cards
* SEO data is automatically created/updated with articles
* Canonical URLs supported via `seo.canonical` (leave empty to use the article's own URL)
* SEO data is optional but recommended for better search visibility

### Category Management

* Articles support multiple categories as an array of strings
* Categories can be used for filtering and organization
* Category filtering endpoint available for easy content discovery

### BlogBuster Integration

* Support for `blog_buster_article_id` field for external article management
* Compatible with existing BlogBuster article import workflows
* Maintains integration with automated article pulling systems