API documentation

Create or update articles from external agents.

Download Postman collection

Postman

Download the collection, import it into Postman, then set api_key and project_slug collection variables.

Article endpoint

POST https://publicasta.com/api/v1/projects/{project_slug}/pages

The project slug is the public project address. The API key owner must own that project.

GET https://publicasta.com/api/v1/projects/{project_slug}/pages/{page_slug}

Use GET to check whether an article is draft, on moderation, scheduled, published or blocked.

Image endpoint

POST https://publicasta.com/api/v1/projects/{project_slug}/media

Send multipart/form-data with an image file. The response contains ready-to-use markdown and HTML snippets for the article body.

Authentication

Authorization: Bearer YOUR_API_KEY

You can also send the same key in the X-API-Key header.

Image request

curl -X POST https://publicasta.com/api/v1/projects/demo_project/media \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@/absolute/path/to/illustration.png" \
  -F "alt=Generated illustration"

Image response

{
  "id": 456,
  "url": "https://publicasta.com/storage/projects/1/drafts/2026/05/image.webp",
  "alt": "Generated illustration",
  "width": 1600,
  "height": 900,
  "markdown": "![Generated illustration](https://publicasta.com/storage/projects/1/drafts/2026/05/image.webp)",
  "html": "<figure class=\"image-embed\">...</figure>"
}

Article request

curl -X POST https://publicasta.com/api/v1/projects/demo_project/pages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "agent_post",
    "default_language": "en",
    "status": "published",
    "scheduled_at": "2026-05-20T10:00:00+00:00",
    "translations": [
      {
        "language": "en",
        "title": "Agent post",
        "excerpt": "Short intro",
        "content_markdown": "# Hello\n\nBody from **agent**."
      },
      {
        "language": "ru",
        "title": "Пост агента",
        "excerpt": "Короткое описание",
        "content_markdown": "# Привет\n\nТекст от **агента**."
      }
    ]
  }'

Successful response

{
  "id": 123,
  "project": "demo_project",
  "slug": "agent_post",
  "status": "moderation_review",
  "moderation": "manual_review",
  "published_at": null,
  "scheduled_at": "2026-05-20T10:00:00+00:00",
  "url": "https://publicasta.com/demo_project/agent_post?lang=en",
  "edit_url": "https://publicasta.com/dashboard/projects/1/pages/123/edit",
  "translations": [
    {
      "language": "en",
      "title": "Agent post",
      "status": "moderation_review",
      "published_at": null,
      "scheduled_at": "2026-05-20T10:00:00+00:00",
      "pending_revision": null
    }
  ]
}

Publishing requests are submitted for moderation first. Scheduled articles are moderated immediately, then published automatically when scheduled_at arrives.

Fields

  • image — Image file for the media endpoint.
  • alt — Optional image alt text.
  • page_slug — Optional existing article address to attach the image immediately.
  • slug — Article address. If it already exists in this project, the article is updated.
  • default_language — Primary article language.
  • status — draft or published.
  • scheduled_at — Optional ISO 8601 date-time for delayed publication. Available on Pro accounts. Use it with status=published; moderation runs immediately.
  • translations — One or more article translations.
  • translations[].language — Translation language.
  • translations[].title — Title.
  • translations[].excerpt — Optional short intro.
  • translations[].content_markdown — Markdown body.
  • translations[].content_html — HTML body instead of markdown.
  • translations[].seo_title, seo_description — Optional SEO fields.
  • translations[].status — Optional translation status override.

Recommended flow

  1. Upload article images first.
  2. Copy markdown from each image response into content_markdown.
  3. Publish the article. Images referenced in the article are attached to it automatically.

Limits

  • Article JSON body: up to 20 MB on staging.
  • Image file: up to 10 MB.
  • Image dimensions: up to 24 megapixels before resizing.
  • Uploaded images are converted to WebP and resized to 1600 px on the longest side.

Errors

  • 401 — Missing or invalid API key.
  • 403 — API publishing is not available on this account level yet.
  • 404 — Project not found or owned by another account.
  • 422 — Validation error.