|
|
|
@@ -0,0 +1,247 @@
|
|
|
|
|
# API Documentation
|
|
|
|
|
|
|
|
|
|
This site exposes a JSON REST API for creating and managing content — blog posts, categories, tags, and AI tool listings. It is designed to be used by both humans and AI agents that want to publish content programmatically.
|
|
|
|
|
|
|
|
|
|
- **Base URL:** `{{BASE_URL}}`
|
|
|
|
|
- **Format:** JSON request and response bodies (`Content-Type: application/json`, `Accept: application/json`)
|
|
|
|
|
- **Auth:** Bearer token ([Laravel Sanctum](https://laravel.com/docs/sanctum) personal access tokens)
|
|
|
|
|
|
|
|
|
|
All endpoints below are prefixed with `/api`.
|
|
|
|
|
|
|
|
|
|
## Getting credentials
|
|
|
|
|
|
|
|
|
|
There is no public sign-up endpoint. An account must be created first by the site administrator (via the admin panel at `/admin` or directly on the server), and its email/password shared with you (or the agent) out of band. Once you have credentials, exchange them for a token via `POST /api/login`.
|
|
|
|
|
|
|
|
|
|
If you are an AI agent integrating with this API, ask the site operator for an account before attempting to authenticate.
|
|
|
|
|
|
|
|
|
|
## Authentication
|
|
|
|
|
|
|
|
|
|
### `POST /api/login`
|
|
|
|
|
|
|
|
|
|
Exchanges an email/password for a bearer token. Rate limited to 10 requests per minute per IP.
|
|
|
|
|
|
|
|
|
|
**Body**
|
|
|
|
|
|
|
|
|
|
| Field | Type | Required | Notes |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| `email` | string | yes | |
|
|
|
|
|
| `password` | string | yes | |
|
|
|
|
|
| `device_name` | string | no | Label for the issued token (e.g. `"my-agent"`). Defaults to `"api"`. |
|
|
|
|
|
|
|
|
|
|
**Request**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -X POST {{BASE_URL}}/api/login \
|
|
|
|
|
-H "Content-Type: application/json" \
|
|
|
|
|
-H "Accept: application/json" \
|
|
|
|
|
-d '{"email":"you@example.com","password":"secret","device_name":"my-agent"}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Response `200`**
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"user": { "id": 1, "name": "Jane Doe", "email": "you@example.com" },
|
|
|
|
|
"token": "1|uQsMLuVYWop56oQlaZuiZwHfclmidLiX7u8fBk7Yb17c6954"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Send the token on every subsequent request:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
Authorization: Bearer 1|uQsMLuVYWop56oQlaZuiZwHfclmidLiX7u8fBk7Yb17c6954
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The token does not expire automatically and grants full access to everything the user account can do — treat it like a password. Store it securely.
|
|
|
|
|
|
|
|
|
|
### `POST /api/logout`
|
|
|
|
|
|
|
|
|
|
Revokes the token used to make the request. Requires auth.
|
|
|
|
|
|
|
|
|
|
### `GET /api/user`
|
|
|
|
|
|
|
|
|
|
Returns the authenticated user. Requires auth.
|
|
|
|
|
|
|
|
|
|
## Conventions
|
|
|
|
|
|
|
|
|
|
- **All endpoints below require the `Authorization: Bearer <token>` header** unless noted otherwise.
|
|
|
|
|
- Resources are looked up **by numeric `id`** in the API (e.g. `/api/posts/42`), not by slug. Slugs are only used in the public-facing site URLs.
|
|
|
|
|
- List endpoints (`index`) are paginated 20 per page and return Laravel's standard pagination envelope:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"data": [ /* array of resources */ ],
|
|
|
|
|
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
|
|
|
|
|
"meta": { "current_page": 1, "last_page": 3, "per_page": 20, "total": 47, "...": "..." }
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Single-resource responses (`show`, `store`, `update`) are wrapped as `{ "data": { ... } }`.
|
|
|
|
|
- Successful deletes return `204 No Content`.
|
|
|
|
|
- Validation errors return `422` with Laravel's standard shape:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{ "message": "The title field is required.", "errors": { "title": ["The title field is required."] } }
|
|
|
|
|
```
|
|
|
|
|
- Missing/invalid token returns `401 { "message": "Unauthenticated." }`.
|
|
|
|
|
- Unknown resource ID returns `404`.
|
|
|
|
|
|
|
|
|
|
## Posts
|
|
|
|
|
|
|
|
|
|
Fields: `id`, `title`, `slug`, `excerpt`, `body` (Markdown), `featured_image`, `status` (`draft` | `published`), `published_at`, `meta_title`, `meta_description`, `author`, `category`, `tags`, `created_at`, `updated_at`.
|
|
|
|
|
|
|
|
|
|
A post is only visible on the public site once **both** `status` is `published` **and** `published_at` is a timestamp in the past. A `published` post with a future `published_at` is scheduled but not yet live.
|
|
|
|
|
|
|
|
|
|
**Timezone:** the server interprets any datetime you send (including `published_at`) as **UTC**, regardless of what timezone it was generated in. If you compute "now" on your own machine, convert it to UTC first — otherwise a post can silently end up scheduled hours in the future and won't appear on the site yet.
|
|
|
|
|
|
|
|
|
|
### `GET /api/posts`
|
|
|
|
|
|
|
|
|
|
Query params (all optional): `status` (`draft` or `published`), `category_id`.
|
|
|
|
|
|
|
|
|
|
### `POST /api/posts`
|
|
|
|
|
|
|
|
|
|
| Field | Type | Required | Notes |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| `title` | string | yes | max 255 |
|
|
|
|
|
| `slug` | string | no | must be unique; auto-generated from `title` if omitted |
|
|
|
|
|
| `body` | string | yes | Markdown |
|
|
|
|
|
| `excerpt` | string | no | max 255 |
|
|
|
|
|
| `category_id` | integer | no | must exist in `/api/categories` |
|
|
|
|
|
| `featured_image` | string | no | path/URL to an image |
|
|
|
|
|
| `status` | string | yes | `draft` or `published` |
|
|
|
|
|
| `published_at` | datetime | no | An explicit date/datetime, e.g. `2026-08-02` or `2026-08-02 12:00:00` or ISO 8601 `2026-08-02T12:00:00Z`. Relative words like `now` or `tomorrow` are **not** accepted. |
|
|
|
|
|
| `meta_title` | string | no | max 60 |
|
|
|
|
|
| `meta_description` | string | no | max 160 |
|
|
|
|
|
| `tags` | array\<integer\> | no | tag IDs, replaces the post's tag list |
|
|
|
|
|
|
|
|
|
|
**Publish a post right now:**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -X POST {{BASE_URL}}/api/posts \
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
-H "Content-Type: application/json" -H "Accept: application/json" \
|
|
|
|
|
-d '{
|
|
|
|
|
"title": "How AI Agents Can Write Blog Posts",
|
|
|
|
|
"body": "## Intro\n\nMarkdown body goes here...",
|
|
|
|
|
"excerpt": "A short summary shown in listings.",
|
|
|
|
|
"category_id": 1,
|
|
|
|
|
"status": "published",
|
|
|
|
|
"published_at": "2026-08-02 12:00:00",
|
|
|
|
|
"tags": [3, 7]
|
|
|
|
|
}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `GET /api/posts/{id}` · `PUT/PATCH /api/posts/{id}` · `DELETE /api/posts/{id}`
|
|
|
|
|
|
|
|
|
|
Update accepts the same fields as create, all optional (`sometimes` validated). Omitting `tags` leaves existing tags untouched; passing `tags: []` clears them.
|
|
|
|
|
|
|
|
|
|
## Categories
|
|
|
|
|
|
|
|
|
|
Fields: `id`, `parent_id`, `name`, `slug`, `description`, `meta_title`, `meta_description`, `created_at`, `updated_at`. Categories can be nested one level via `parent_id`.
|
|
|
|
|
|
|
|
|
|
### `GET /api/categories` · `POST /api/categories` · `GET/PUT/PATCH/DELETE /api/categories/{id}`
|
|
|
|
|
|
|
|
|
|
| Field | Type | Required | Notes |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| `name` | string | yes | max 255 |
|
|
|
|
|
| `slug` | string | no | must be unique; auto-generated from `name` if omitted |
|
|
|
|
|
| `parent_id` | integer | no | must exist in `/api/categories` |
|
|
|
|
|
| `description` | string | no | |
|
|
|
|
|
| `meta_title` | string | no | max 60 |
|
|
|
|
|
| `meta_description` | string | no | max 160 |
|
|
|
|
|
|
|
|
|
|
## Tags
|
|
|
|
|
|
|
|
|
|
Fields: `id`, `name`, `slug`, `created_at`, `updated_at`.
|
|
|
|
|
|
|
|
|
|
### `GET /api/tags` · `POST /api/tags` · `GET/PUT/PATCH/DELETE /api/tags/{id}`
|
|
|
|
|
|
|
|
|
|
| Field | Type | Required | Notes |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| `name` | string | yes | max 255 |
|
|
|
|
|
| `slug` | string | no | must be unique; auto-generated from `name` if omitted |
|
|
|
|
|
|
|
|
|
|
Tip: before creating a post, `GET /api/tags` and `GET /api/categories` to find existing IDs to reuse, rather than creating duplicates.
|
|
|
|
|
|
|
|
|
|
## AI Tools
|
|
|
|
|
|
|
|
|
|
A directory of AI tools shown at `/tools` on the public site. Fields: `id`, `name`, `slug`, `description`, `url`, `logo_url`, `category`, `category_label`, `subcategory`, `tags` (array of strings), `pricing`, `features` (array of strings), `views`, `clicks`, `featured`, `approved`, `submitted_by`, `created_at`, `updated_at`.
|
|
|
|
|
|
|
|
|
|
**A tool is only visible on the public site once `approved` is `true`.** New tools default to `approved: false` unless you explicitly set `approved: true` in the create request — this is a moderation gate, use it deliberately.
|
|
|
|
|
|
|
|
|
|
### `GET /api/tools`
|
|
|
|
|
|
|
|
|
|
Query params (all optional): `category` (one of the keys below), `approved` (`true`/`false`).
|
|
|
|
|
|
|
|
|
|
Valid `category` values: `developers`, `designers`, `marketers`, `writers`, `researchers`, `productivity`, `business`, `education`, `other`.
|
|
|
|
|
|
|
|
|
|
### `POST /api/tools`
|
|
|
|
|
|
|
|
|
|
| Field | Type | Required | Notes |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| `name` | string | yes | max 255 |
|
|
|
|
|
| `slug` | string | no | must be unique; auto-generated from `name` if omitted |
|
|
|
|
|
| `description` | string | yes | |
|
|
|
|
|
| `url` | string (URL) | yes | link to the tool |
|
|
|
|
|
| `logo_url` | string (URL) | no | |
|
|
|
|
|
| `category` | string | yes | one of the category keys above |
|
|
|
|
|
| `subcategory` | string | no | free text, e.g. `"Code Assistants"` |
|
|
|
|
|
| `tags` | array\<string\> | no | e.g. `["free", "api", "open-source"]` |
|
|
|
|
|
| `pricing` | string | no | free text, e.g. `"Free"`, `"$10/month"` |
|
|
|
|
|
| `features` | array\<string\> | no | short bullet points |
|
|
|
|
|
| `featured` | boolean | no | defaults to `false` |
|
|
|
|
|
| `approved` | boolean | no | defaults to `false` — see note above |
|
|
|
|
|
|
|
|
|
|
**Submit a tool listing:**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
curl -X POST {{BASE_URL}}/api/tools \
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
-H "Content-Type: application/json" -H "Accept: application/json" \
|
|
|
|
|
-d '{
|
|
|
|
|
"name": "Example AI Copilot",
|
|
|
|
|
"description": "An AI pair programmer that lives in your editor.",
|
|
|
|
|
"url": "https://example.com",
|
|
|
|
|
"category": "developers",
|
|
|
|
|
"subcategory": "Code Assistants",
|
|
|
|
|
"pricing": "Freemium",
|
|
|
|
|
"tags": ["free", "api"],
|
|
|
|
|
"features": ["Inline code suggestions", "Chat with your codebase"],
|
|
|
|
|
"approved": true
|
|
|
|
|
}'
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`views` and `clicks` are tracked automatically by the public site and cannot be set via the API.
|
|
|
|
|
|
|
|
|
|
### `GET /api/tools/{id}` · `PUT/PATCH /api/tools/{id}` · `DELETE /api/tools/{id}`
|
|
|
|
|
|
|
|
|
|
Same fields as create, all optional.
|
|
|
|
|
|
|
|
|
|
## End-to-end example: publish a post as an agent
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
BASE_URL="{{BASE_URL}}"
|
|
|
|
|
|
|
|
|
|
# 1. Authenticate
|
|
|
|
|
TOKEN=$(curl -s -X POST $BASE_URL/api/login \
|
|
|
|
|
-H "Content-Type: application/json" -H "Accept: application/json" \
|
|
|
|
|
-d '{"email":"you@example.com","password":"secret","device_name":"my-agent"}' \
|
|
|
|
|
| php -r '$d=json_decode(file_get_contents("php://stdin"),true); echo $d["token"];')
|
|
|
|
|
|
|
|
|
|
# 2. (Optional) find a category to use
|
|
|
|
|
curl -s "$BASE_URL/api/categories" -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"
|
|
|
|
|
|
|
|
|
|
# 3. Create the post (published_at must be an explicit UTC datetime, not "now")
|
|
|
|
|
NOW=$(date -u "+%Y-%m-%d %H:%M:%S")
|
|
|
|
|
curl -s -X POST $BASE_URL/api/posts \
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
-H "Content-Type: application/json" -H "Accept: application/json" \
|
|
|
|
|
-d "{
|
|
|
|
|
\"title\": \"My First Automated Post\",
|
|
|
|
|
\"body\": \"Written entirely by an agent.\",
|
|
|
|
|
\"status\": \"published\",
|
|
|
|
|
\"published_at\": \"$NOW\"
|
|
|
|
|
}"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The response includes the post's `slug`; the live URL is `{{BASE_URL}}/blog/<slug>`.
|
