Canvas

https://github.com/austintoddj/canvas
Admin
Canvas is an open-source publishing platform for Laravel that provides a distraction-free editor,...
Tokens:67,028
Snippets:489
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### SettingsRepository usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-settings.md

Demonstrates setting, getting, masking, and forgetting an AI API key using the SettingsRepository singleton. The set method stores the value encrypted, get decrypts it, mask shows a bullet-masked version, and forget clears the row.

```php
use Canvas\Support\SettingsRepository;
use Canvas\Enums\SettingKey;

$settings = app(SettingsRepository::class);
$settings->set(SettingKey::AiApiKey, 'sk-...');          // stored encrypted
$key = $settings->get(SettingKey::AiApiKey);             // decrypted
echo SettingsRepository::mask($key);                     // ••••••••1234
$settings->forget(SettingKey::AiApiKey);                 // clear
```

--------------------------------

### Install dependencies with Composer and npm

Source: https://github.com/austintoddj/canvas/blob/main/AGENTS.md

Run these commands from the repository root to install PHP and JavaScript dependencies. composer install uses the lock file, and npm ci performs a clean install respecting package-lock.json.

```bash
composer install
```

```bash
npm ci
```

--------------------------------

### Install Canvas with Composer and Artisan

Source: https://github.com/austintoddj/canvas/blob/main/readme.md

Run these commands to install Canvas and run its installer. Requires PHP >= 8.3 and Laravel >= 12.

```bash
composer require austintoddj/canvas
php artisan canvas:install
```

--------------------------------

### GET api/media/create

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Returns a skeleton for creating a new media item.

```APIDOC
## GET api/media/create

### Description
Returns a skeleton for creating a new media item.

### Method
GET

### Endpoint
api/media/create

### Response
#### Success Response (200)
- **media** (object) - A new media object with default values.

#### Response Example
{
  "media": {}
}
```

--------------------------------

### Canvas console command examples

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/console-commands.md

Example invocations of various Canvas console commands, including making a user admin, assigning a role, listing roles/users, and pruning webhook deliveries and post revisions.

```bash
php artisan canvas:make-admin you@example.com
php artisan canvas:assign-role you@example.com Editor
php artisan canvas:roles
php artisan canvas:users
php artisan canvas:prune-webhook-deliveries --days=60
php artisan canvas:prune-post-revisions --keep=100
```

--------------------------------

### MediaStorage usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-media.md

Shows how to instantiate MediaStorage via the make() factory and store an uploaded file, returning metadata for persistence. The delete method is also demonstrated.

```php
use Canvas\Support\MediaStorage;

$storage = MediaStorage::make();
$meta = $storage->store($request->file('file'));       // array returned for persistence
$storage->delete($meta['path']);
```

--------------------------------

### MediaUrl usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-media.md

Shows how to normalize a picked URL for persistence using toStoredMediaReference and generate an absolute URL for egress using absolute.

```php
use Canvas\Support\MediaUrl;

// persistence
$post->featured_image = MediaUrl::toStoredMediaReference($pickedUrl);

// egress
$ogImage = MediaUrl::absolute($post->featured_image);
```

--------------------------------

### GET api/posts/create

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Returns a fresh post skeleton for creating a new post.

```APIDOC
## GET api/posts/create

### Description
Returns a fresh post skeleton for creating a new post.

### Method
GET

### Endpoint
api/posts/create

### Response
#### Success Response (200)
- **post** (object) - A new post object with default values.

#### Response Example
{
  "post": {}
}
```

--------------------------------

### GET /{view?}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Serves the SPA shell for the Canvas frontend. Renders the layout with boot data and locale settings.

```APIDOC
## GET /{view?}

### Description
Serves the SPA shell for the Canvas frontend. Renders the layout with boot data and locale settings.

### Method
GET

### Endpoint
/{view?}

### Parameters
#### Path Parameters
- **view** (string) - Optional - View name (unused, SPA handles routing)

### Response
#### Success Response (200)
- **html** (string) - Rendered HTML page

#### Response Example
<!DOCTYPE html>
<html>
  <head>...</head>
  <body>...</body>
</html>
```

--------------------------------

### GET api/stats Response JSON

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Example response for the GET api/stats endpoint. The response includes views, visits, graph data, month-over-month comparisons, top referers, and counts for library and pipeline. The 'days' field defaults to 30 and 'scope=all' is only honored for users with PostPolicy::viewAll.

```json
{
  "views": 0, "visits": 0,
  "graph": { "views": "{\"2026-09-22\":12,...}", "visits": "{}" },
  "monthOverMonthViews": { "direction": "up", "percentage": "25", "comparable": true },
  "monthOverMonthVisits": { "direction": "down", "percentage": "0", "comparable": false },
  "topReferers": { "google.com": 3 },
  "days": 30,
  "library": { "published": 0, "drafts": 0, "scheduled": 0, "pending_updates": 0 },
  "pipeline": { "drafts": [], "scheduled": [], "pending": [] },
  "recent_posts": [],
  "top_posts": []
}
```

--------------------------------

### CanvasUser usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/model-canvas-user.md

Usage example for CanvasUser: checking admin status, updating a user's profile fields, and granting admin access via updateOrCreate (equivalent to canvas:make-admin).

```php
use Canvas\Models\CanvasUser;
use Canvas\Enums\Role;

if (CanvasUser::isAdmin($user)) {
    // grant access, manage users, taxonomy, integrations
}

$row = CanvasUser::query()->findOrFail($user->getKey());
$row->update([
    'username' => 'taylor',
    'theme' => 'dark',
    'digest' => true,
]);

// Grant access + role directly (equivalent of canvas:make-admin)
CanvasUser::query()->updateOrCreate(
    ['user_id' => $user->getKey()],
    ['role' => Role::Admin],
);
```

--------------------------------

### GET api/users

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Lists all users. Requires the `manage-users` permission.

```APIDOC
## GET api/users

### Description
Lists all users. Requires the `manage-users` permission.

### Method
GET

### Endpoint
api/users

### Response
#### Success Response (200)
- **data** (array) - List of users.

#### Response Example
{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    }
  ]
}
```

--------------------------------

### GET api/users/create

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Returns a skeleton or empty form for creating a new user. Requires the `manage-users` permission.

```APIDOC
## GET api/users/create

### Description
Returns a skeleton or empty form for creating a new user. Requires the `manage-users` permission.

### Method
GET

### Endpoint
api/users/create

### Response
#### Success Response (200)
- **data** (object) - Empty or default resource structure.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### GET api/tags/create / api/topics/create

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Returns a skeleton or empty form for creating a new tag or topic.

```APIDOC
## GET api/tags/create / api/topics/create

### Description
Returns a skeleton or empty form for creating a new tag or topic.

### Method
GET

### Endpoint
api/tags/create or api/topics/create

### Response
#### Success Response (200)
- **data** (object) - Empty or default resource structure.

#### Response Example
{
  "data": {}
}
```

--------------------------------

### Localization usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-utilities.md

Demonstrates resolving a user's locale, fetching the translation dictionary as JSON for the SPA, and checking if the language is right-to-left. Uses the Canvas\Support\Localization facade.

```php
use Canvas\Support\Localization;

$locale = Localization::resolveLocale($user->locale);
$dictionary = Localization::availableTranslations($locale); // JSON for the SPA
$rtl = Localization::isRightToLeftLanguage($locale);
```

--------------------------------

### Webhook payload example

Source: https://github.com/austintoddj/canvas/blob/main/docs/webhooks.md

Example JSON payload sent to your webhook URL. It includes metadata but not the full HTML body; fetch the post separately if needed. The event field uses the event id (e.g., post.published).

```json
{
    "api_version": 1,
    "event": "post.published",
    "delivery_id": "…",
    "created_at": "2026-07-22T15:04:05+00:00",
    "data": {
        "id": "…",
        "slug": "…",
        "title": "…",
        "summary": "…",
        "published_at": "…",
        "featured_image": "…",
        "meta": {},
        "topic": { "name": "…", "slug": "…" },
        "tags": [{ "name": "…", "slug": "…" }],
        "author": { "id": 1, "name": "Jane", "username": "jane" }
    }
}
```

--------------------------------

### Upgrade Canvas

Source: https://github.com/austintoddj/canvas/blob/main/readme.md

Run these commands to update Canvas and apply any migrations or publish assets. Follow the upgrade guide for major versions.

```bash
composer update austintoddj/canvas
php artisan canvas:migrate
php artisan canvas:publish
```

--------------------------------

### GET api/media/{media}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a single media item.

```APIDOC
## GET api/media/{media}

### Description
Retrieves a single media item.

### Method
GET

### Endpoint
api/media/{media}

### Parameters
#### Path Parameters
- **media** (string) - Required - The media ID.

### Response
#### Success Response (200)
- **media** (object) - The media object.

#### Response Example
{
  "media": {}
}
```

--------------------------------

### SocialProfiles usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-utilities.md

Demonstrates normalizing a social handle and building a profile URL. normalizeHandle strips @ and converts known host URLs to bare handles; profileUrl returns base + handle or null for unknown platforms/empty handles.

```php
use Canvas\Support\SocialProfiles;

$handle = SocialProfiles::normalizeHandle('x', 'https://x.com/@taylorotwell'); // taylorotwell
$url = SocialProfiles::profileUrl('bluesky', 'todd.bsky.social');
```

--------------------------------

### GET api/integrations

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves the current integration settings, including Unsplash, AI, and webhook configurations.

```APIDOC
## GET api/integrations

### Description
Retrieves the current integration settings, including Unsplash, AI, and webhook configurations.

### Method
GET

### Endpoint
api/integrations

### Response
#### Success Response (200)
- **unsplash** (object) - Unsplash configuration
- **ai** (object) - AI configuration
- **webhooks** (object) - Webhook configuration

#### Response Example
{
  "unsplash": {
    "access_key": "string"
  },
  "ai": {
    "provider": "string",
    "model": "string"
  },
  "webhooks": {
    "url": "string",
    "events": ["post.published"]
  }
}
```

--------------------------------

### Media model usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/model-media.md

Shows direct usage of the Media model: querying with scopes, iterating results to access appended url and type attributes, and generating an absolute URL via MediaUrl::absolute.

```php
use Canvas\Models\Media;

// list the current user's images matching a term, newest first
$media = Media::query()
    ->ownedBy($user)
    ->search('sunset')
    ->ofMimeType('image/')
    ->latest()
    ->paginate();

// serialization includes mounted url/type
foreach ($media as $m) {
    echo $m->url;    // /storage/canvas/images/abc.png
    echo $m->type;   // "image"
}

// following a stored reference for external consumers
$abs = \Canvas\Support\MediaUrl::absolute($m->url, 'https://example.com');
```

--------------------------------

### HostUser usage example

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-utilities.md

Shows how to use the HostUser resolver to find a user by identifier (email or ID). The findByIdentifierOrFail method throws ModelNotFoundException on miss.

```php
use Canvas\Support\HostUser;

$user = HostUser::findByIdentifierOrFail($request->input('q')); // email or id
```

--------------------------------

### GET api/posts/{post}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a single post with its associated tags and topics.

```APIDOC
## GET api/posts/{post}

### Description
Retrieves a single post with its associated tags and topics.

### Method
GET

### Endpoint
api/posts/{post}

### Parameters
#### Path Parameters
- **post** (string) - Required - The post ID or slug.

### Response
#### Success Response (200)
- **post** (object) - The full post object including tags and topics.

#### Response Example
{
  "post": {}
}
```

--------------------------------

### GET api/users/{user}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a single user by ID.

```APIDOC
## GET api/users/{user}

### Description
Retrieves a single user by ID.

### Method
GET

### Endpoint
api/users/{user}

### Parameters
#### Path Parameters
- **user** (integer) - Required - The ID of the user.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier.
- **name** (string) - User's name.
- **email** (string) - User's email.

#### Response Example
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}
```

--------------------------------

### GET api/unsplash

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Proxies the Unsplash search/photos endpoint. Requires a configured Unsplash access key.

```APIDOC
## GET api/unsplash

### Description
Proxies the Unsplash search/photos endpoint. Requires a configured Unsplash access key.

### Method
GET

### Endpoint
api/unsplash

### Parameters
#### Query Parameters
- **query** (string) - Required - Search query
- **page** (integer) - Optional - Page number, min 1
- **per_page** (integer) - Optional - Items per page, 1-30

### Response
#### Success Response (200)
- **results** (array) - List of Unsplash photos

#### Error Response (422)
- **message** (string) - Error message
- **code** (string) - Error code
```

--------------------------------

### Check AI configuration and get default model

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-ai.md

Uses the static `Ai` class to check if AI is configured and retrieve the default model. The `model()` method returns the `AiModel` override if set, otherwise the provider's default model.

```php
use Canvas\Support\Ai;

if (Ai::configured()) {
    $default = Ai::model(); // e.g. "gpt-4o-mini" unless overridden
}
```

--------------------------------

### GET api/users/lookup

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Looks up a user by email or ID. Requires the `manage-users` permission.

```APIDOC
## GET api/users/lookup

### Description
Looks up a user by email or ID. Requires the `manage-users` permission.

### Method
GET

### Endpoint
api/users/lookup

### Parameters
#### Query Parameters
- **q** (string) - Required - Email or ID to search for.

### Response
#### Success Response (200)
- **user** (object) - The matched user.

#### Response Example
{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}
```

--------------------------------

### GET api/integrations/webhooks/deliveries/{delivery}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a single webhook delivery by ID.

```APIDOC
## GET api/integrations/webhooks/deliveries/{delivery}

### Description
Retrieves a single webhook delivery by ID.

### Method
GET

### Endpoint
api/integrations/webhooks/deliveries/{delivery}

### Parameters
#### Path Parameters
- **delivery** (string) - Required - Delivery ID

### Response
#### Success Response (200)
- **id** (string) - Delivery ID
- **event** (string) - Event name
- **url** (string) - Webhook URL
- **status** (string) - Delivery status
- **http_status** (integer) - HTTP status code
- **attempts** (integer) - Number of attempts
- **payload** (object) - Payload sent
- **response_body** (string) - Response body
- **error_message** (string) - Error message if any
- **post_id** (string) - Related post ID
- **finished_at** (string) - Completion timestamp
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Update timestamp
```

--------------------------------

### GET api/posts/{post}/revisions/{revision}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a specific revision of a post.

```APIDOC
## GET api/posts/{post}/revisions/{revision}

### Description
Retrieves a specific revision of a post.

### Method
GET

### Endpoint
api/posts/{post}/revisions/{revision}

### Parameters
#### Path Parameters
- **post** (string) - Required - The post ID or slug.
- **revision** (string) - Required - The revision ID.

### Response
#### Success Response (200)
- **revision** (object) - The full revision object.

#### Response Example
{
  "revision": {}
}
```

--------------------------------

### Using UserResource and CanvasUserResource in a response

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/http-requests-resources.md

Example of using both resources together in a JSON response. UserResource::make($hostUser)->resolve() includes the canvas sliver, and CanvasUserResource::toProfileArray($canvasUser) provides the profile array.

```php
use Canvas\Http\Resources\UserResource;
use Canvas\Http\Resources\CanvasUserResource;

return response()->json([
    'user' => UserResource::make($hostUser)->resolve(),   // with canvas sliver
    'canvas' => CanvasUserResource::toProfileArray($canvasUser),
]);
```

--------------------------------

### GET api/translations/{locale}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Returns the full flat translation dictionary for the given locale.

```APIDOC
## GET api/translations/{locale}

### Description
Returns the full flat translation dictionary for the given locale.

### Method
GET

### Endpoint
api/translations/{locale}

### Parameters
#### Path Parameters
- **locale** (string) - Required - Locale code, e.g., 'en'

### Response
#### Success Response (200)
- **key** (string) - Translation key
- **value** (string) - Translated string

#### Response Example
{
  "app.title": "My App"
}
```

--------------------------------

### GET api/users/{user}/posts

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Lists posts authored by a specific user.

```APIDOC
## GET api/users/{user}/posts

### Description
Lists posts authored by a specific user.

### Method
GET

### Endpoint
api/users/{user}/posts

### Parameters
#### Path Parameters
- **user** (integer) - Required - The ID of the user.

### Response
#### Success Response (200)
- **data** (array) - List of posts.

#### Response Example
{
  "data": [
    {
      "id": 1,
      "title": "Example Post"
    }
  ]
}
```

--------------------------------

### Catching AiWritingException and handling error codes

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/errors.md

Shows how to catch AiWritingException and use a match expression on the errorCode to handle different failure scenarios, such as not configured, quota exceeded, timeout, and generic failures. The example uses AiWritingService::rewrite() with AiWritingAction::Improve.

```php
use Canvas\Exceptions\AiWritingException;

try {
    $result = (new AiWritingService())->rewrite(
        AiWritingAction::Improve,
        $text,
    );
} catch (AiWritingException $e) {
    match ($e->errorCode) {
        AiWritingException::CodeNotConfigured => // show "set up AI in Integrations"
        AiWritingException::CodeQuotaExceeded => // show billing message
        AiWritingException::CodeTimeout => // show retry message
        default => // generic failure with $e->getMessage()
    };
}
```

--------------------------------

### GET api/integrations/webhooks/deliveries

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Lists webhook deliveries with optional filtering by status, event, and pagination.

```APIDOC
## GET api/integrations/webhooks/deliveries

### Description
Lists webhook deliveries with optional filtering by status, event, and pagination.

### Method
GET

### Endpoint
api/integrations/webhooks/deliveries

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by status: pending, success, failed
- **event** (string) - Optional - Filter by event name
- **per_page** (integer) - Optional - Items per page, 1-50, default 15

### Response
#### Success Response (200)
- **id** (string) - Delivery ID
- **event** (string) - Event name
- **url** (string) - Webhook URL
- **status** (string) - Delivery status
- **http_status** (integer) - HTTP status code
- **attempts** (integer) - Number of attempts
- **payload** (object) - Payload sent
- **response_body** (string) - Response body
- **error_message** (string) - Error message if any
- **post_id** (string) - Related post ID
- **finished_at** (string) - Completion timestamp
- **created_at** (string) - Creation timestamp
- **updated_at** (string) - Update timestamp
```

--------------------------------

### GET api/posts/{post}/revisions

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a list of revisions for a specific post.

```APIDOC
## GET api/posts/{post}/revisions

### Description
Retrieves a list of revisions for a specific post.

### Method
GET

### Endpoint
api/posts/{post}/revisions

### Parameters
#### Path Parameters
- **post** (string) - Required - The post ID or slug.

### Response
#### Success Response (200)
- **revisions** (array) - List of revision objects.

#### Response Example
{
  "revisions": []
}
```

--------------------------------

### GET api/media

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a paginated list of media items. Supports search, MIME type filtering, sorting, and scope parameters.

```APIDOC
## GET api/media

### Description
Retrieves a paginated list of media items. Supports search, MIME type filtering, sorting, and scope parameters.

### Method
GET

### Endpoint
api/media

### Parameters
#### Query Parameters
- **search** (string) - Optional - Search term.
- **mime** (string) - Optional - Filter by MIME type.
- **sort** (string) - Optional - Sort order, e.g., `oldest`.
- **scope** (string) - Optional - Set to `all` to include all media.
- **perPage** (integer) - Optional - Number of items per page (default 15).

### Response
#### Success Response (200)
- **media** (array) - List of media objects.
- **pagination** (object) - Pagination metadata.

#### Response Example
{
  "media": [],
  "pagination": {}
}
```

--------------------------------

### GET api/tags/{tag} / api/topics/{topic}

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a single tag or topic by its slug or ID.

```APIDOC
## GET api/tags/{tag} / api/topics/{topic}

### Description
Retrieves a single tag or topic by its slug or ID.

### Method
GET

### Endpoint
api/tags/{tag} or api/topics/{topic}

### Parameters
#### Path Parameters
- **tag** (string) - Required - The slug or ID of the tag.
- **topic** (string) - Required - The slug or ID of the topic.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier.
- **name** (string) - Name of the tag/topic.
- **slug** (string) - URL-friendly slug.

#### Response Example
{
  "id": 1,
  "name": "example",
  "slug": "example"
}
```

--------------------------------

### Show a single post by slug with SEO

Source: https://github.com/austintoddj/canvas/blob/main/docs/content.md

Defines a GET route that returns a single published post by slug, including related tags, topic, and user, along with SEO metadata. Returns 404 if the post is not found.

```php
Route::get('/blog/posts/{slug}', function (string $slug) {
    $post = Post::published()
        ->with(['tags:name,slug', 'topic:id,name,slug', 'user:id,name'])
        ->firstWhere('slug', $slug) ?? abort(404);

    return [
        'post' => $post,
        'seo' => PostSeo::resolve($post, url("/blog/{$slug}")),
    ];
});
```

--------------------------------

### GET api/tags / api/topics

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Lists all tags or topics with optional search and sorting. Includes post counts and supports pagination.

```APIDOC
## GET api/tags / api/topics

### Description
Lists all tags or topics with optional search and sorting. Includes post counts and supports pagination.

### Method
GET

### Endpoint
api/tags or api/topics

### Parameters
#### Query Parameters
- **search** (string) - Optional - Filter by name (LIKE).
- **sort** (string) - Optional - Sort order: `posts`, `name`, or default latest.
- **perPage** (integer) - Optional - Number of items per page (default 10).

### Response
#### Success Response (200)
- **posts_count** (integer) - Number of posts associated with the tag/topic.
- **pagination** (object) - Pagination metadata.

#### Response Example
{
  "data": [
    {
      "id": 1,
      "name": "example",
      "slug": "example",
      "posts_count": 5
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 1
  }
}
```

--------------------------------

### GET api/search

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Searches for posts, tags, topics, and users. Results are limited to 10 per type.

```APIDOC
## GET api/search

### Description
Searches for posts, tags, topics, and users. Results are limited to 10 per type.

### Method
GET

### Endpoint
api/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search term
- **type** (string) - Optional - Type to search: post, tag, topic, user. Empty means all allowed.

### Response
#### Success Response (200)
- **id** (string) - Item ID
- **title** (string) - Item title (for posts/topics)
- **name** (string) - Item name (for tags/users)
- **type** (string) - Item type
- **route** (string) - Route to the item

#### Response Example
[
  {
    "id": "uuid",
    "title": "Post title",
    "type": "post",
    "route": "/posts/uuid"
  }
]
```

--------------------------------

### Using PublishedAt to validate and store publish time

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-lifecycle.md

Example usage of PublishedAt: validates that the input has a timezone offset or Z, then parses and converts to storage string for assignment to $post->published_at.

```php
use Canvas\Support\PublishedAt;

if (! PublishedAt::hasTimezone($input)) {
    throw new InvalidArgumentException('A timezone offset or Z is required.');
}
$post->published_at = PublishedAt::toStorageString(PublishedAt::parse($input));
```

--------------------------------

### Run PHP tests with Pest

Source: https://github.com/austintoddj/canvas/blob/main/AGENTS.md

Use composer test to run the Pest test suite. Additional variants include parallel execution, JUnit output, coverage with a 98% minimum, database group tests, and an install smoke test.

```bash
composer test            # vendor/bin/pest
```

```bash
composer test:ci         # parallel + junit → build/junit.xml
```

```bash
composer test:parallel
```

```bash
composer test:coverage   # --min=98 (pcov)
```

```bash
composer test:coverage:html  # build/coverage/
```

```bash
composer test:database   # --group=database (set DB_CONNECTION=mysql|pgsql)
```

```bash
composer test:install-smoke  # bash bin/install-smoke.sh
```

```bash
composer test -- --filter=LocalizationTest
```

--------------------------------

### List published posts with pagination

Source: https://github.com/austintoddj/canvas/blob/main/docs/content.md

Defines a GET route that returns a paginated list of published posts, selecting specific fields and eager loading related topic and user. Use this endpoint to fetch a collection of blog posts for a public API.

```php
use Canvas\Models\Post;
use Canvas\Support\PostSeo;

Route::get('/blog/posts', function () {
    return Post::published()
        ->select(['id', 'slug', 'title', 'summary', 'featured_image', 'published_at', 'user_id', 'topic_id'])
        ->with(['topic:id,name,slug', 'user:id,name'])
        ->latest()
        ->paginate(10);
});
```

--------------------------------

### GET api/posts

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves a list of posts. Use the `type` query parameter to filter drafts or published posts, and `scope` to include all posts for non-contributors.

```APIDOC
## GET api/posts

### Description
Retrieves a list of posts. Use the `type` query parameter to filter drafts or published posts, and `scope` to include all posts for non-contributors.

### Method
GET

### Endpoint
api/posts

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter to `draft` for drafts, otherwise returns published posts.
- **scope** (string) - Optional - Set to `all` to include all posts for non-contributors.

### Response
#### Success Response (200)
- **posts** (array) - List of post objects.

#### Response Example
{
  "posts": []
}
```

--------------------------------

### GET api/posts/{post}/stats

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves analytics insights for a specific post. Returns a 422 error if the post is not published.

```APIDOC
## GET api/posts/{post}/stats

### Description
Retrieves analytics insights for a specific post. The post must be published; otherwise, a 422 error is returned.

### Method
GET

### Endpoint
api/posts/{post}/stats

### Parameters
#### Path Parameters
- **post** (string) - Required - The post ID (route-model binding).

### Response
#### Success Response (200)
Returns the PostInsights shape as described in api-reference/analytics.md.

#### Error Response (422)
- **message** (string) - Error message.
- **code** (string) - Error code, e.g., 'stats_published_only'.

#### Response Example (Error)
{
  "message": "Post is not published.",
  "code": "stats_published_only"
}
```

--------------------------------

### GET api/tags/{tag}/posts / api/topics/{topic}/posts

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Lists posts associated with a specific tag or topic, including view counts and pagination.

```APIDOC
## GET api/tags/{tag}/posts / api/topics/{topic}/posts

### Description
Lists posts associated with a specific tag or topic, including view counts and pagination.

### Method
GET

### Endpoint
api/tags/{tag}/posts or api/topics/{topic}/posts

### Parameters
#### Path Parameters
- **tag** (string) - Required - The slug or ID of the tag.
- **topic** (string) - Required - The slug or ID of the topic.

### Response
#### Success Response (200)
- **data** (array) - List of posts.
- **views_count** (integer) - Number of views for each post.
- **pagination** (object) - Pagination metadata.

#### Response Example
{
  "data": [
    {
      "id": 1,
      "title": "Example Post",
      "views_count": 100
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 10,
    "total": 1
  }
}
```

--------------------------------

### Build and run the SPA with Vite

Source: https://github.com/austintoddj/canvas/blob/main/AGENTS.md

Use npm run dev for local development with hot reload, npm run build for a production build that writes to resources/dist (commit this output), and npm run preview to preview the production build locally.

```bash
npm run dev              # Vite; writes resources/dist/canvas.hot
```

```bash
npm run build            # production → resources/dist/ (commit this)
```

```bash
npm run preview
```

--------------------------------

### GET api/calendar/posts

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves posts for the calendar view within a specified date range. Requires the 'from' and 'to' query parameters and returns a list of posts with their scheduling status.

```APIDOC
## GET api/calendar/posts

### Description
Retrieves posts for the calendar view within a specified date range. The range must be 92 days or less.

### Method
GET

### Endpoint
api/calendar/posts

### Parameters
#### Query Parameters
- **from** (string, date) - Required - Start date in Y-m-d format.
- **to** (string, date) - Required - End date in Y-m-d format. Must be within 92 days of 'from'.

### Response
#### Success Response (200)
- **posts** (array) - List of posts, each with:
  - **id** (string) - Post ID.
  - **title** (string) - Post title.
  - **slug** (string) - Post slug.
  - **published_at** (string) - Publication date.
  - **featured_image** (string) - URL of featured image.
  - **status** (string) - Either 'published' or 'scheduled'.
  - **user** (object|null) - Lite author payload or null.

#### Response Example
{
  "posts": [
    {
      "id": "uuid",
      "title": "Example Post",
      "slug": "example-post",
      "published_at": "2026-09-22T10:00:00Z",
      "featured_image": "https://example.com/image.jpg",
      "status": "published",
      "user": {
        "id": "user-id",
        "name": "Author Name"
      }
    }
  ]
}
```

--------------------------------

### Run preflight checks

Source: https://github.com/austintoddj/canvas/blob/main/AGENTS.md

Run the preflight script to check dependencies, lint, build, and run Pint. This is the recommended command before committing.

```bash
bash bin/preflight.sh    # or: npm run preflight | composer preflight
```

--------------------------------

### GET api/stats

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/endpoints.md

Retrieves dashboard analytics including views, visits, graphs, month-over-month comparisons, top referrers, library counts, pipeline data, recent posts, and top posts. Requires authentication and appropriate permissions.

```APIDOC
## GET api/stats

### Description
Retrieves dashboard analytics including views, visits, graphs, month-over-month comparisons, top referrers, library counts, pipeline data, recent posts, and top posts.

### Method
GET

### Endpoint
api/stats

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Number of days for analytics: 7, 30, 90, or 365. Default is 30. Any other value defaults to 30.
- **scope** (string) - Optional - Set to 'all' to include all posts. Only honored when the user passes PostPolicy::viewAll (i.e., not a Contributor).

### Response
#### Success Response (200)
- **views** (integer) - Total view count.
- **visits** (integer) - Total visit count.
- **graph** (object) - Contains 'views' and 'visits' as JSON strings mapping dates to counts.
- **monthOverMonthViews** (object) - Contains 'direction' (string), 'percentage' (string), 'comparable' (boolean).
- **monthOverMonthVisits** (object) - Contains 'direction' (string), 'percentage' (string), 'comparable' (boolean).
- **topReferers** (object) - Map of referrer domain to count.
- **days** (integer) - The number of days used.
- **library** (object) - Contains 'published', 'drafts', 'scheduled', 'pending_updates' (integers).
- **pipeline** (object) - Contains 'drafts', 'scheduled', 'pending' (arrays).
- **recent_posts** (array) - List of recent posts, each with id, title, summary, featured_image, published_at, created_at, updated_at, views_count, has_pending_changes.
- **top_posts** (array) - List of top posts, each with id, title, views.

#### Response Example
{
  "views": 0,
  "visits": 0,
  "graph": {
    "views": "{\"2026-09-22\":12,...}",
    "visits": "{}"
  },
  "monthOverMonthViews": {
    "direction": "up",
    "percentage": "25",
    "comparable": true
  },
  "monthOverMonthVisits": {
    "direction": "down",
    "percentage": "0",
    "comparable": false
  },
  "topReferers": {
    "google.com": 3
  },
  "days": 30,
  "library": {
    "published": 0,
    "drafts": 0,
    "scheduled": 0,
    "pending_updates": 0
  },
  "pipeline": {
    "drafts": [],
    "scheduled": [],
    "pending": []
  },
  "recent_posts": [],
  "top_posts": []
}
```

--------------------------------

### Using DashboardInsights and PostInsights directly

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/analytics.md

Shows how to invoke the analytics classes directly. Fetches published post IDs, creates a DashboardInsights instance for a 30-day window, and retrieves the views count. Also demonstrates creating PostInsights for a single post and serializing it to JSON for an API response. Relies on Eloquent's findOrFail for missing posts.

```php
use Canvas\Analytics\DashboardInsights;
use Canvas\Analytics\PostInsights;
use Canvas\Models\Post;

$ids = Post::query()->published()->pluck('id');
$dashboard = DashboardInsights::for($ids, days: 30);
echo $dashboard->views;

$post = Post::findOrFail($id);
$insights = PostInsights::for($post);
$json = $insights->jsonSerialize(); // ready for response()->json()
```

--------------------------------

### Configure storage disk and path

Source: https://github.com/austintoddj/canvas/blob/main/docs/configuration.md

Sets the storage disk to public and the path prefix to canvas.

```env
CANVAS_STORAGE_DISK=public
CANVAS_STORAGE_PATH=canvas
```

--------------------------------

### Registering container singletons in register()

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/canvas-service-provider.md

Registers four singletons: MediaStorage, MediaService, SettingsRepository, and WebhookEndpointRepository with a concrete implementation.

```php
$this->app->singleton(MediaStorage::class, static fn (): MediaStorage => MediaStorage::make());
$this->app->singleton(MediaService::class);
$this->app->singleton(SettingsRepository::class);
$this->app->singleton(WebhookEndpointRepository::class, SettingsWebhookEndpointRepository::class);
```

--------------------------------

### Implement WebhookEndpointRepository with custom endpoint list

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/events-jobs-mail.md

Shows a custom repository implementing the contract, returning a list of WebhookEndpoint objects. The host provider then binds the interface to this custom class using the singleton method.

```php
use Canvas\Contracts\WebhookEndpointRepository;
use Canvas\Enums\WebhookEvent;
use Canvas\Support\WebhookEndpoint;

class MyRepository implements WebhookEndpointRepository
{
    /** @return list<WebhookEndpoint> */
    public function enabledFor(WebhookEvent $event): array
    {
        return [new WebhookEndpoint('https://example.com/hook', 'my-secret')];
    }
}

// host provider
$this->app->singleton(WebhookEndpointRepository::class, MyRepository::class);
```

--------------------------------

### Create a manual revision checkpoint with label

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-lifecycle.md

Create a manual session-end checkpoint with a user-provided label, similar to the editor's 'save history' action. Uses RevisionReason::Left and a label of 'Version 2'.

```php
use Canvas\Support\RecordPostRevision;
use Canvas\Enums\RevisionReason;

$revision = RecordPostRevision::fromPost($post, $user->id, RevisionReason::Left, 'Version 2');
```

--------------------------------

### Create and publish a post

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/model-post.md

Creates a new post with a UUID, sets slug, title, body, user_id, and published_at, then saves it. Also syncs tags and associates a topic. This is typically driven by PostController::store but works directly with the model.

```php
use Canvas\Models\Post;
use Illuminate\Support\Str;

$post = new Post(['id' => (string) Str::uuid()]);
$post->slug = 'hello-canvas';
$post->title = 'Hello Canvas';
$post->body = '...';
$post->user_id = $user->id;
$post->published_at = now()->format('Y-m-d H:i:s');
$post->save();

$post->tags()->sync($tagIds);       // sync through canvas_posts_tags
$post->topic()->associate($topic);  // or set $post->topic_id
```

--------------------------------

### CanvasServiceProvider class skeleton

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/canvas-service-provider.md

Shows the class declaration with register() and boot() methods, as used in the Canvas package's service provider.

```php
class CanvasServiceProvider extends ServiceProvider
{
    public function register(): void { ... }
    public function boot(): void { ... }
}
```

--------------------------------

### Publish Canvas configuration file

Source: https://github.com/austintoddj/canvas/blob/main/docs/configuration.md

Publishes the config/canvas.php file so you can change defaults.

```bash
php artisan vendor:publish --tag=canvas-config
```

--------------------------------

### Canvas\Support\DigestPeriod

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-utilities.md

Represents a digest period constructed per recipient timezone. Provides formatted start and end labels.

```APIDOC
## `Canvas\Support\DigestPeriod`

### Description
Represents a digest period constructed per recipient timezone. Provides formatted start and end labels.

### Method
Constructed by `DigestCommand` per recipient timezone.

### Properties
- **formattedStart** - Localized `M j` label for the period start.
- **formattedEnd** - Localized `M j` label for the period end.

### Notes
- See `types.md` for field definitions.
```

--------------------------------

### FrontendBootData::forUser method signature

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-utilities.md

Defines the public static method that builds the SPA boot payload. Returns an array containing languages, upload limits, user roles, timezone, locale, translations, and other configuration flags. Consumed by ViewController::__invoke.

```php
public static function forUser(Authenticatable $user): array
```

--------------------------------

### Extend Canvas gates with Gate::before and Gate::define

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/policies-middleware.md

Shows how hosts can extend Canvas gates in their own providers. The Gate::before callback returns null to fall through to Canvas gates, and Gate::define registers a custom 'viewAny' ability using the PostPolicy's viewAll method.

```php
use Canvas\Models\Post;
use Illuminate\Support\Facades\Gate;

Gate::before(function ($user, $ability) {
    return null; // fall through to Canvas gates
});

Gate::define('viewAny', [\Canvas\Policies\PostPolicy::class, 'viewAll']);
```

--------------------------------

### Run PHP linting, formatting, and static analysis

Source: https://github.com/austintoddj/canvas/blob/main/AGENTS.md

Use composer pint to fix PHP code style, composer pint:test to check without modifying, and composer lint to run PHPStan analysis at level 6 via Larastan.

```bash
composer pint            # fix PHP (vendor/bin/pint)
```

```bash
composer pint:test       # check only
```

```bash
composer lint            # vendor/bin/phpstan analyse (phpstan.neon.dist)
```

--------------------------------

### Run Canvas tests

Source: https://github.com/austintoddj/canvas/blob/main/readme.md

Run the test suite for Canvas.

```bash
composer test
```

--------------------------------

### Rewrite text and generate SEO with AiWritingService

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-ai.md

Instantiates `AiWritingService` and calls `rewrite` for grammar fixing and SEO suggestion. The SEO action returns an array with `title` and `description`; other actions return a string.

```php
use Canvas\Support\AiWritingService;
use Canvas\Enums\AiWritingAction;

$writer = new AiWritingService();

$text = $writer->rewrite(
    AiWritingAction::FixGrammar,
    "the post's original body...",
    title: 'My Post Title',
);

[$seoTitle, $seoDesc] = array_values(
    $writer->rewrite(AiWritingAction::SuggestSeo, $post->body)
);
```

--------------------------------

### Run JavaScript linting, formatting, and type checking

Source: https://github.com/austintoddj/canvas/blob/main/AGENTS.md

Use npm run lint to run ESLint on resources/js, npm run format to run Prettier, and npm run typecheck to run TypeScript with noEmit.

```bash
npm run lint             # eslint . (resources/js/**/*.{ts,tsx})
```

```bash
npm run format           # prettier --write .
```

```bash
npm run typecheck        # tsc --noEmit (typescript-7)
```

--------------------------------

### MediaService class constructor

Source: https://github.com/austintoddj/canvas/blob/main/_autodocs/api-reference/support-media.md

The MediaService is a final readonly class injected as a container singleton. Its constructor takes a MediaStorage instance, which it uses to manage uploads, overwrites, and deletes against the storage disk.

```php
final readonly class MediaService
{
    public function __construct(
        private MediaStorage $mediaStorage,
    ) {}
}
```
Tokens:
Raw