Dokumentacja Mumro

Co mozna umiescic w tresci

Edytor obsluguje akapity, naglowki H2/H3, pogrubienie, kursywe, cytaty, listy, linki, obrazy do 20 MB, tryb HTML oraz osadzenia wideo z YouTube, Vimeo, Facebooka, TikToka i Dailymotion. Ostateczny wyglad i dopuszczalny HTML zaleza od docelowego CMS i stylow strony.

Statusy i problemy

Statusy lokalne to draft, scheduled, published, failed i archived. Przy statusie failed sprawdz komunikat bledu przy artykule, popraw konfiguracje lub dane i ponow publikacje. Po awarii sieci sprawdz rowniez strone docelowa, bo CMS mogl zapisac wpis mimo utraty odpowiedzi.

Zalecany przeplyw

Organizacja jest workspace/tenantem API, a site_id identyfikuje nalezaca do niej strone WWW. Nie jest to identyfikator workspace.

Konfiguracja strony i CMS przez API

Zwykle konfiguracje wykonuje uzytkownik w UI. Agent moze jednak dodac strone przez POST /api/website-analytics/sites, zapisac integracje przez PUT /api/website-analytics/sites/{site_id}/cms i sprawdzic ja przez POST /api/website-analytics/sites/{site_id}/cms/test.

{
  "cms_type": "wordpress",
  "cms_endpoint_url": "https://example.com",
  "cms_username": "mumro-publisher",
  "cms_secret": "WORDPRESS_APPLICATION_PASSWORD"
}

{
  "cms_type": "custom",
  "cms_endpoint_url": "https://example.com/api/mumro/articles",
  "cms_secret": "LONG_RANDOM_SHARED_BEARER_TOKEN"
}

API nie zwraca zapisanego sekretu; pokazuje tylko cms_has_secret. Pominiecie cms_secret przy aktualizacji zachowuje obecny sekret, a clear_secret=true go usuwa.

curl https://app.mumro.io/api/website-analytics/sites \
  -H "Authorization: Bearer smm_REPLACE_ME"

curl -X POST https://app.mumro.io/api/website-articles \
  -H "Authorization: Bearer smm_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "site_id": 12,
    "title": "Artykul utworzony przez API",
    "slug": "artykul-utworzony-przez-api",
    "excerpt": "Krotki opis",
    "content_html": "<h2>Wprowadzenie</h2><p>Tresc artykulu.</p>",
    "metadata_json": {
      "source": "customer-crm",
      "source_record_id": "article-123"
    }
  }'

curl -X POST https://app.mumro.io/api/website-articles/123/visuals \
  -H "Authorization: Bearer smm_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: article-123-visual-v1" \
  -d '{
    "visual_style": "editorial",
    "cover_mode": "template",
    "visual_format": "square",
    "content_density": "detailed",
    "brand_label": "Mumro",
    "carousel_enabled": true,
    "slide_count": 6,
    "include_sources_slide": true,
    "use_as_featured_image": true
  }'

Wynik ma format 1080 x 1350 px albo 1080 x 1080 px (zalezne od visual_format) i wraca w polu visual_bundle artykulu. Uporzadkowane carousel_asset_ids mozna od razu wykorzystac przy publikacji social media z image_mode="carousel". Tryb template nie zuzywa kredytow obrazu; cover_mode="ai" wymaga gotowego generatora obrazow i rozlicza image.generate.

curl -X POST https://app.mumro.io/api/website-articles/123/publish \
  -H "Authorization: Bearer smm_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{"remote_status":"publish"}'

Tworzenie artykulu - pola

Tryby publikacji

Idempotencja tworzenia

Dla jednego logicznego utworzenia zawsze ponawiaj ten sam Idempotency-Key. Pierwszy request zwraca 201, identyczna powtorka 200 i ten sam artykul, a ten sam klucz z innym payloadem zwraca 422 idempotency_key_conflict. Nowy artykul musi dostac nowy klucz.

Wlasny endpoint CMS

Mumro testuje endpoint przez GET z Bearer tokenem. Przy publikacji wysyla POST z naglowkami X-Mumro-Article-Id i X-Mumro-Site-Id oraz obiektem article i site.

{
  "article": {
    "id": 123,
    "external_id": null,
    "title": "Tytul",
    "slug": "tytul",
    "excerpt": "Zajawka",
    "content_html": "<p>Tresc</p>",
    "status": "publish",
    "scheduled_at": null,
    "metadata": { "source_record_id": "article-123" }
  },
  "site": {
    "id": 12,
    "name": "Strona klienta",
    "site_url": "https://example.com",
    "domain": "example.com"
  }
}

Endpoint powinien dzialac jako upsert: najpierw po article.external_id, a gdy go nie ma, po stabilnej parze site.id + article.id. To zabezpiecza przed duplikatami po utracie odpowiedzi sieciowej.

{
  "external_id": "post-456",
  "external_url": "https://example.com/blog/tytul",
  "status": "published"
}

{
  "publication_type": "post|story|reel|film",
  "targets": ["<account_id>"],
  "common_content": {
    "caption": "Hello world",
    "hashtags": ["smm", "automation"],
    "media_asset_ids": ["<media_asset_id>"],
    "subtitle_asset_id": "<srt_media_asset_id>",
    "subtitle_locale": "pl_PL",
    "first_comment_text": "Prepared first comment for IG/FB post or reel",
    "title": "optional (required for film)",
    "description": "optional",
    "cover": { "kind": "frame_at_seconds", "t": 1.5 },
    "platform_options": {
      "youtube": { "privacy": "unlisted", "tags": ["api"] },
      "tiktok": { "privacy_level": "SELF_ONLY", "disable_comment": true },
      "x": { "content_type": "thread", "thread": ["tweet 1", "tweet 2"] },
      "linkedin": { "content_type": "article", "url": "https://example.com" }
    }
  },
  "overrides": {
    "<account_id>": {
      "caption_override": "...",
      "hashtags_override": ["..."],
      "media_override": ["<media_asset_id>"],
      "story_options": { "link_sticker_url": "https://example.com" },
      "cover_override": { "kind": "asset", "asset_id": 123 },
      "title_override": "...",
      "description_override": "...",
      "subtitle_asset_id": "<srt_media_asset_id>",
      "subtitle_locale": "pl_PL",
      "first_comment_text": "Prepared first comment for this target",
      "tags_override": ["yt", "tags"],
      "share_to_feed": true,
      "fb_title": "Facebook reel title",
      "fb_comment_text": "Legacy Facebook-only first comment alias",
      "is_trial": true,
      "platform_options": { "privacy": "private" },
      "scheduled_at": "2026-07-01T15:00:00+02:00",
      "target_ig": true,
      "target_fb": false
    }
  },
  "schedule_mode": "draft|now|next_slot|custom",
  "scheduled_at": "2026-07-01T15:00:00+02:00",
  "scheduled_at_per_target": {
    "<account_id>": "2026-07-01T15:00:00+02:00"
  }
}

Scheduling contract

Gdy schedule_mode jest pominiete albo ma wartosc next_slot, API uzywa harmonogramu konta i zapisuje job jako schedule_source="auto". custom wymaga scheduled_at i zapisuje manual. now publikuje natychmiastowo poza harmonogramem, tez jako manual. Dla posta draft zapisuje edytowalny szkic bez joba workera.

GET /api/publish-jobs pokazuje schedule_source. Wartosci auto moga byc przeliczane przez harmonogram. Wartosci manual sa poza harmonogramem i nie sa ruszane przez jego przeliczenia. Gdy auto ma scheduled_at=null, job nadal nalezy do harmonogramu i nie jest publikowany natychmiastowo.

GET /api/publications/preview-schedule?account_id=10&content_type=reel&is_trial=true

Gdy is_trial jest pominiete, API uzywa domyslnej wartosci ig_trial_reels konta. Odpowiedz zwraca rozstrzygniete is_trial i tablice warnings. Kod trial_reel_schedule_requires_is_trial oznacza, ze zwykly Reel nie ma slotu, ale konto ma dostepny slot Trial Reel.

Automatyczny scheduler jest globalnie dlawiony: jezeli kilka pozycji jest gotowych w tym samym ticku, Mumro wrzuca do publikacji najwyzej jedna i zostawia pozostale na kolejne przebiegi. Scheduler czeka tez, gdy publikacja juz trwa albo kolejka publikacji ma zaleglosc, wiec opozniony harmonogram nie powinien wypchnac wielu postow naraz.

PATCH /api/publish-jobs/123
{
  "schedule_source": "auto"
}

PATCH /api/publish-jobs/123
{
  "scheduled_at": "2026-07-15T18:00:00+02:00"
}

POST /api/publish-jobs/123/move
{
  "position": 1,
  "schedule_policy": "shift_schedule"
}

schedule_policy="keep_time" zmienia kolejnosc listy, oznacza przesuwany job jako manual i nie zmienia dat innych jobow.

Adapter-facing keys

Dla targetow Instagram/Facebook pola fb_title, first_comment_text, fb_comment_text i is_trial mozna przekazac bezposrednio w overrides[account_id] albo wewnatrz overrides[account_id].platform_options. Pola bezposrednie wygrywaja, jesli oba warianty sa obecne.

first_comment_text dodaje przygotowany pierwszy komentarz po udanej publikacji posta albo rolki Instagram/Facebook. Mozna go podac w common_content.first_comment_text, overrides[account_id].first_comment_text albo w odpowiednim platform_options. Wyslanie komentarza jest best-effort: jego stan widac jako first_comment_status i first_comment_results. Blad komentarza nie oznacza nieudanej publikacji; mozna ponowic tylko komentarz przez POST /api/publish-jobs/{id}/retry-first-comment. fb_comment_text zostaje jako zgodny wstecz alias tylko dla Facebooka.

Dla obrazow upload zwraca trwaly public_url oraz krotko wazny, podpisany download_url. W HTML artykulu zapisuj tylko public_url; download_url sluzy do natychmiastowego podgladu. Publikacja i planowanie sa blokowane, jesli po normalizacji pozostaje obraz z X-Amz-Expires. Dla grafiki glownej uzyj featured_image_asset_id, featured_image_alt i opcjonalnego featured_image_caption; odpowiedz zawiera trwaly featured_image_url.

Napisy SRT sa natywnymi napisami Meta/Facebook dla wideo. Uploaduj plik .srt jako asset subtitle i przekaz jego numeryczne id jako subtitle_asset_id. Pole jest wykonywane tylko dla powierzchni Facebook Reel (target_fb=true). Instagram Reels Graph API nie przyjmuje plikow SRT; target tylko IG z subtitle_asset_id zostanie odrzucony z media_asset_invalid. subtitle_locale domyslnie ma wartosc pl_PL i musi miec format Meta, np. pl_PL albo en_US.

Zeby uzyc tego samego MP4 na Instagramie i Facebooku, uploaduj plik raz przez POST /api/uploads/direct albo presigned upload i przekaz zwrocone numeryczne id w common_content.media_asset_ids. Nie tworz osobnych uploadow per platforma, chyba ze pliki naprawde sie roznia.

{
  "publication_id": "<uuid5 of (organization, idempotency_key)>",
  "request_id": "<X-Request-Id>",
  "jobs": [
    {
      "target_id": "<account_id>",
      "job_id": "<queue_job_id_or_film_job_id | null>",
      "status": "draft|scheduled|queued|succeeded|failed",
      "schedule_source": "auto|manual|null",
      "scheduled_at": "ISO-8601 | null",
      "error_code": "string | null",
      "error_message": "string | null"
    }
  ],
  "summary": { "error_code": "all_targets_failed" }
}

Odpowiedzi JSON deklaruja Content-Type: application/json; charset=utf-8. Nieznana sciezka /api/* zwraca JSON 404 api_route_not_found i nie przechodzi do fallbacku SPA.

Token sluzy tylko do tego requestu w przegladarce i nie jest zapisywany.

{
  "platforms": {
    "instagram_facebook": {
      "supported_types": ["post", "reel", "story"],
      "caption_limits": { "post": 2200, "reel": 2200, "story": 0 },
      "platform_options": {
        "content_type": {
          "type": "enum",
          "values": ["auto", "image", "video"],
          "supported_on_create": true,
          "supported_on_edit": false,
          "legacy_only": false,
          "unavailable": false
        },
        "fb_title": {
          "type": "string",
          "max_length": 255,
          "supported_on_create": true,
          "supported_on_edit": true,
          "legacy_only": false,
          "unavailable": false,
          "accepted_locations": [
            "common_content.platform_options.instagram_facebook.fb_title",
            "overrides.*.platform_options.fb_title",
            "overrides.*.fb_title"
          ]
        },
        "first_comment_text": {
          "type": "string",
          "max_length": 2000,
          "surface": "instagram_facebook_post_reel",
          "supported_on_create": true,
          "supported_on_edit": false,
          "legacy_only": false,
          "unavailable": false,
          "accepted_locations": [
            "common_content.first_comment_text",
            "common_content.platform_options.instagram_facebook.first_comment_text",
            "overrides.*.first_comment_text",
            "overrides.*.platform_options.first_comment_text"
          ],
          "reason": "Posted best-effort after an Instagram/Facebook post or reel is published. Comment failure does not fail the publication."
        },
        "is_trial": {
          "type": "boolean",
          "supported_on_create": true,
          "supported_on_edit": true,
          "legacy_only": false,
          "unavailable": false,
          "accepted_locations": [
            "common_content.platform_options.instagram_facebook.is_trial",
            "overrides.*.platform_options.is_trial",
            "overrides.*.is_trial"
          ]
        },
        "subtitle_asset_id": {
          "type": "integer",
          "asset_type": "subtitle",
          "format": "srt",
          "surface": "facebook_reel",
          "supported_on_create": true,
          "supported_on_edit": false,
          "legacy_only": false,
          "unavailable": false,
          "accepted_locations": [
            "common_content.subtitle_asset_id",
            "overrides.*.subtitle_asset_id"
          ],
          "reason": "Executed only for the Facebook Reel/video surface. Instagram Reels Graph API does not accept SRT caption files."
        },
        "subtitle_locale": {
          "type": "string",
          "default": "pl_PL",
          "format": "meta_locale",
          "surface": "facebook_reel",
          "supported_on_create": true,
          "supported_on_edit": false,
          "legacy_only": false,
          "unavailable": false,
          "accepted_locations": [
            "common_content.subtitle_locale",
            "overrides.*.subtitle_locale"
          ]
        },
        "share_to_feed": {
          "type": "boolean",
          "supported_on_create": false,
          "supported_on_edit": false,
          "legacy_only": false,
          "unavailable": true,
          "reason": "Not currently executed by the Instagram/Facebook publishing adapter."
        }
      }
    }
  },
  "media_limits": {
    "post": { "types": ["image/jpeg", "image/png", "image/webp"], "max_mb": 10, "count_max": 10 },
    "reel": { "types": ["video/mp4", "video/quicktime"], "max_mb": 500, "count_max": 1 }
  },
  "story_options": {
    "instagram_facebook": {
      "link_sticker_url": { "type": "url", "max_length": 2000 }
    }
  }
}

Kazda opcja w platform_options ma metadane wykonania: supported_on_create, supported_on_edit, legacy_only i unavailable. Dla Instagram/Facebook is_trial, fb_title, first_comment_text i fb_comment_text mozna wyslac bezposrednio w overrides[account_id] albo w overrides[account_id].platform_options. first_comment_text mozna tez podac raz w common_content.first_comment_text; komentarz jest dodawany best-effort po udanym poscie albo rolce IG/FB.