# Content endpoint reference

Understand the requests Monok sends to your content endpoint and what it expects back.

## Requests and authentication

- GET /info authenticates the connection and returns your site metadata. Without getSiteInfo, it returns a minimal Custom CMS profile.
- POST /push accepts article JSON. The action field is draft or publish. A legacy action query parameter takes precedence when present. If neither is supplied, the Fetch handler passes draft and the Express router leaves action undefined. Treat an omitted action as a draft in your Express callback.
- GET /postfilter searches published content when searchArticles is configured and returns 404 when it is unavailable.

Monok sends the workspace key as token for pushes. Both GET routes accept X-API-Key and return private, no-cache responses. The adapters also accept the legacy apikey query parameter. Endpoint paths are relative to the base you entered in Publish To.

```bash
curl --fail-with-body -H "X-API-Key: ${MONOK_API_KEY}" https://example.com/api/monok/info
```

## Delivery and publication

A push needs a Monok id and a non-empty title. Optional fields include content (HTML), text (Markdown with widget blocks), slug, description, author, categories, tags, sections, language, type, thumbnail URL, inline JPEG data, and thumbnail alt text. Preserve the Monok ID for repeat delivery and publication linkbacks.

```json
{
  "id": "article-123",
  "title": "A guide to weekend hikes",
  "slug": "weekend-hikes",
  "action": "draft",
  "content": "<p>Choose a route that suits your group.</p>",
  "language": "en",
  "tags": ["Outdoors"]
}
```

The adapter responds after onArticle returns. Save the article or durably queue the work before returning. An accepted delivery can still be a draft or await publication.

```json
{ "ok": true, "status": "accepted", "monokId": "article-123" }
```

## Report the published URL

Call sendMonokLinkback once the canonical URL is public. For drafts or queued work, call it from your CMS publication hook. The default endpoint is https://app.monok.com/api/v1/linkback. Set monokBaseUrl in the second argument only for a different Monok environment.

```javascript
import { sendMonokLinkback } from "@monok/server";

await sendMonokLinkback({
  monokId: article.id,
  externalId: published.id,
  url: published.url,
  title: article.title,
  thumbnailUrl: published.thumbnailUrl,
});
```

externalId and thumbnailUrl are optional. Supply the CMS record ID and a publicly accessible image URL when available. The Fetch entry point also exports sendMonokLinkback.

## Adapter options

- apiKey and onArticle are required. The callback gets the article and action. Express also provides saveThumbImage.
- getSiteInfo accepts a metadata object or a function. searchArticles accepts a function that returns the matching records. Both functions can be async.
- Express imageDir controls the output directory for JPEGs. maxImageBytes sets the decoded limit, which defaults to 15 MiB. Express parses JSON up to 20 MiB.
- Express basePath adds a prefix within the Express mount and defaults to an empty string. If you mount the router at /api/monok, leave basePath unset.
- The Fetch handler uses basePath as the full request-path prefix, defaulting to /api/monok. maxBodyBytes defaults to 20 MiB. The host controls image storage.

## Handle article thumbnails

The thumbnail field is a URL. thumbImageData is an inline JPEG as raw base64 or a JPEG data URL. Express saveThumbImage optionally takes a filename stem and returns a local path when it saves an image. In a Fetch runtime, decodeThumbImage returns a Uint8Array when inline data is present. Store or serve the result through your own CMS or asset storage.

## Expose CMS metadata

Use getSiteInfo to populate the destination’s publishing choices. Return your site name, logo, categories, post types, tags, authors, and optional languages. The adapter adds its package version.

```typescript
import type { SiteInfoInput } from "@monok/server";

const siteInfo: SiteInfoInput = {
  js_scripts: "Disabled",
  name: "Example Journal",
  logo: "https://example.com/logo.png",
  categories: ["Editorial", "News"],
  post_types: ["post", "page"],
  tags: ["Outdoors"],
  languages: { en: { name: "English", slug: "en", locale: "en_US" } },
  authors: [{
    id: "1",
    name: "Jane Doe",
    profile: "Editor",
    avatar: "https://example.com/authors/jane.jpg",
    roles: ["editor"],
  }],
};

// Pass getSiteInfo: siteInfo to the adapter.
```

## Search published articles

With searchArticles enabled, Monok can discover existing content for coverage checks and linking. Apply the requested post type, section, tag, text query, and pagination to published records in your CMS. The adapter passes post\_type as postType and q as query. The defaults are post type post, amount 10, and page 1.

```bash
curl --fail-with-body -H "X-API-Key: ${MONOK_API_KEY}" "https://example.com/api/monok/postfilter?post_type=post&section=Editorial&tag=Outdoors&q=hike&amount=10&page=1"
```

```json
[
  {
    "canonical_url": "https://example.com/blog/weekend-hikes",
    "post_id": "cms-123",
    "title": "A guide to weekend hikes",
    "description": "Find a route for your next weekend outdoors."
  }
]
```

Return an array of these records. post\_id can be a string or number. title and description can be null. Return an empty array when nothing matches.

## Troubleshooting

- Authentication rejected: Check that your server uses the current workspace API key.
- Endpoint not found: Check that the configured URL is the API base, without /info or /push.
- Accepted but no published article: Check draft status, your queue, and your CMS adapter.

## Related guides

- [Install @monok/server](https://docs.monok.com/integrations/content-api/quickstart) — Set up a content endpoint, connect it to Monok, and check your first delivery.
- [Rotate your API key](https://docs.monok.com/rotate-api-key) — Replace a workspace API key and verify the integrations that depend on it.