Sections API

Endpoints

Get Sections

GET /core/v1/sections

{
  "filters": [
    <section filter>,
    <section filter>,
    ...
  ],
  "chunk": {
    "limit": 10,
    "offset": 20
  },
  "extensions": {
    "ancestors": {"limit": 10},
    "descendants": {"limit": 10},
    "images": {"limit": 10}
  }
}

200 OK

{
  "sections": [
    {
      "id": 1539243,
      "slug": "some-section",
      "path": "top-level-section/some-other-section/parent-section/some-section",
      "title": "Some Section",
      "order_id": 1234,
      "visibility": "listed",  // can be "unlisted" and "private"
      "ancestors": [
        {"id": 123456, "slug": "top-level-section"},
        ...
        {"id": 654321, "slug": "parent-section"},
      ],
      "meta_info": {
        "image": {"id": 12345, "extension": "png"}  // can be null
      }
    },
    ...
  ],
  "extensions": {
    "ancestors": [
      {"id": 123456, "slug": "top-level-section", ...},
      {"id": 654321, "slug": "parent-section", ...},
      ...
    ],
    "descendants": [
      {"id": 4657568, "slug": "some-child-section", ...},
      {"id": 4563564, "slug": "another-child-section", ...},
    ],
    "images": {
      {"id": 12345, "href": "https://assets.rebelmouse.io/path/to/image/12345.png"},
      ...
    }
  }
}

Hints:

Create Section

POST /core/v1/sections

{
  "slug": "some-section",
  "parent_section_id": 123456,  // or null
  "commands": [
    <section command>,
    <section command>,
    ...
  ]
}

200 OK

{
  "section": {
    "id": 1539243,
    "slug": "some-section",
    "path": "path/to/some-section",
    "title": "",
    ...
  }
}

Hints:

Get Section

GET /core/v1/sections/1539243

200 OK

{
  "section": {
    "id": 1539243,
    "slug": "some-section",
    "path": "path/to/some-section",
    "title": "Some Section",
    "visibility": "listed",  // can be "unlisted" and "private"
    "ancestors": [
      {"id": 123456, "slug": "top-level-section"},
      ...
      {"id": 654321, "slug": "parent-section"},
    ],
    "access": {
      "read_access_type": "public",  // can be "restricted" and "restricted_inherited"
    },
    "settings": {
      "open_in_new_tab": false,
      "allow_community_posts": false,
      "hide_from_entry_editor": false,
      "lock_posts_after_publishing": false
    },
    "meta_info": {
      "image": {"id": 12345, "extension": "png"},  // can be null
      "extras": {
        "key": "value",
        ...
      },
      "link_out": "https://example.com/",  // can be null
      "about_html": "Hello <b>world!</b>",
      "meta_title": "Some meta title",  // can be null
      "meta_tags": ["tag-1", "tag-2"],  // can be null
      "breadcrumb_title": "Breadcrumb Title",  // can be null
      "facebook_author_name": "@great.publisher"  // can be null
    }
  }
}

Update Section

PUT /core/v1/sections/1539243

{
  "commands": [
    <section command>,
    <section command>,
    ...
  ]
}

200 OK

{
  "section": {
    "id": 1539243,
    "slug": "some-section",
    "path": "path/to/some-section",
    "title": "Some Section",
    ...
  }
}

Hints:

Remove Sections (async/await)

Async

POST /core/v1/sections/remove

{
  "section_ids": [1539243, 1539244, ...],
  "posts_action": <posts_action>
}

200 OK

{
  "task": {
    "id": "38e9eea7-fc5b-4373-90f0-cb2d59109113",
    "is_ready": false,
    "progress": null,
    "response": null,
    "exception": null
}

Await

GET /core/v1/sections/remove?task_id=38e9eea7-fc5b-4373-90f0-cb2d59109113

200 OK

{
  "task": {
    "id": "38e9eea7-fc5b-4373-90f0-cb2d59109113",
    "is_ready": true,
    "progress": null,
    "response": {
      "removed_section_ids": [1539243, 1539244, 2738456, 12365126, ...]
    },
    "exception": null
}

Hints:

Section Filters

  • {“ids”: [12345, 67890]} – filter by ids

  • {“slugs”: [“section-1”, “section-2”]} – filter by slugs

  • {“paths”: [“path/to/section-1”, “path/to/section-2”]} – filter by paths

  • {“titles”: [“Section 1”, “Section 2”]} – filter by titles

  • {“phrase”: {“phrase”: “hello world”, “syntax”: <phrase filter syntax>}} – filter by title with the specified syntax (see: Phrase Filter Syntaxes)

  • {“visibility”: [“listed”, “unlisted”, “private”]} – filter by visibility (see: Section Visibility Statuses)

  • {“read_access”: [“public”, “restricted”, “restricted_inherited”]} – filter by read access (see: Section Read Access Types)

  • {“link_outs”: {}} – keep only link-outs

  • {“allow_community_posts”: {}} – keep only sections with community posts allowed

  • {“lock_posts_after_publishing”: {}} – keep only sections with posts locked after publishing

  • {“exclude_home”: {}} – exclude home section

  • {“exclude_defaults”: {}} – exclude default sections (for now, it”s only home section)

  • {“exclude_link_outs”: {}} – exclude link-outs

  • {“exclude_read_only”: {}} – exclude read-only sections (usually, it”s sections in an unfinished process of removal)

  • {“level”: {“top”: {}}} – keep only top-level sections

  • {“trees”: {“roots”: [“56789”, “90123”]}} – keep only sections that are in the trees with the specified roots, including the roots

  • {“children”: {“of”: [“12345”, “56789”]}} – keep only children of the specified sections

  • {“descendants”: {“of”: [“345678”, “78901”]}} – keep only descendants of the specified sections

  • {“$exclude”: <section filter>} – exclude sections that match the specified filter

Phrase Filter Syntaxes

  • {“prefix”: {“case_sensitive”: false}} – filter by prefix

  • {“substring”: {“case_sensitive”: false}} – filter by substring

Section Commands

  • {“set-page”: {“role”: “web”}} – creates a page for the section (does nothing at the moment but reserved for the future where the connection between Sections and Pages is more explicit)

  • {“set-slug”: “some-section”} – set section slug

  • {“set-title”: “Some section title”} – set section title

  • {“set-parent”: 123456} – set parent section

  • {“set-visibility”: <visibility status>} – set section visibility (see: Section Visibility Statuses)

  • {“set-access”: {“read_access_type”: <read_access_type>}} – configure section access

  • {“set-settings”: {“open_in_new_tab”: false, “allow_community_posts”: false, “hide_from_entry_editor”: false, “lock_posts_after_publishing”: false}} – configure section settings

  • {“set-meta-info”: {“image”: {“id”: 12345, “extension”: “png”}, “extras”: {“key”: “value”}, “link_out”: “https://example.com/”, “about_html”: “Hello <b>world!</b>”, “meta_title”: “Some meta title”, “meta_tags”: [“tag-1”, “tag-2”], “breadcrumb_title”: “Breadcrumb Title”, “facebook_author_name”: “@great.publisher”}} – set section meta info

Section Visibility Statuses

  • listed – section is visible in the section list

  • unlisted – section is not visible in the section list, but it”s accessible by direct link

  • private – section is not visible in the section list and it”s not accessible by direct link

Section Read Access Types

  • public – everyone can read the section

  • restricted – only users with access can read the section

  • restricted_inherited – only users with access can read the section, but the access is inherited from the parent section

Posts Actions

  • {“keep”: {}} – keep posts

  • {“move”: {“target_section_id”: 123456}} – move posts to the specified section