API Reference | Grigora

Welcome to the Grigora API reference. Our API allows you to programmatically manage your CMS content, enabling powerful integrations and workflow automation.

All API endpoints are rooted at the following base URL:

https://api.grigora.co/general/api/v1

Authentication is handled via an API Key passed in the Authorization header. For details on generating a key, please see our guide: Creating and Authorizing an API Key.

Content-Type Header

For all POST requests made to the Grigora API, you must specify how you are sending data in the request body. The API expects data to be formatted as a standard web form. Therefore, it is essential to include the Content-Type header in your requests and set its value to application/x-www-form-urlencoded. Failing to include this header or using an incorrect content type will result in an error and prevent the API from processing your request.

CMS: Posts

The following endpoints allow you to interact with the posts in your Grigora project's CMS.

List Posts

Retrieves a list of all posts within a project, with options for advanced filtering and sorting.

POST /cms/post/list

Body Parameters

Parameter	Type	Required	Description
`filters`	Object	Optional	An object containing key-value pairs to filter the posts. See the Filters table below for all options.
`sort`	String	Optional	The field to sort the results by (e.g., `last_update`, `title`). Defaults to publish/update time.
`order`	String	Optional	The sort order. Can be `asc` (ascending) or `dsc` (descending). Defaults to `dsc`.

Filters Object

The filters parameter can contain any of the following keys:

Filter Key	Type	Description
`status`	String	Filter by post status. Accepts `published` or `draft`.
`last_update`	Object	Filter by last update timestamp. Object should contain `from` and/or `to` keys with Unix timestamps as values.
`post_publish`	Object	Filter by publish date. Object should contain `from` and/or `to` keys with Unix timestamps as values.
`title`	String	Filter by a substring in the post title (case-insensitive).
`word_count`	Number	Filter for posts with a word count less than or equal to the provided value.
`categories`	String or Array of Strings	Filter for posts belonging to one or more category slugs.
`authors`	String or Array of Strings	Filter for posts by one or more author IDs.
`score`	Object	Filter by SEO score. Object should contain `from` and/or `to` keys with integer values (0-10).
`internal_links`	Number	Filter for posts with internal links less than or equal to the provided value.
`external_links`	Number	Filter for posts with external links less than or equal to the provided value.

Example Request

JSON

{
  "filters": {
    "status": "published",
    "categories": ["news", "featured"],
    "score": {
      "from": 7,
      "to": 10
    }
  },
  "sort": "last_update",
  "order": "dsc"
}

Example Success Response (200)

JSON

{
  "success": true,
  "data": [
    {
      "pk": "project-your_project_id",
      "sk": "cms-post-data-post_id_1",
      "title": "My First Published Post",
      "slug": "my-first-published-post",
      "status": "published",
      "author": "api-user",
      "last_update": 1678886400,
      "first_published": 1678880000,
      "...": "..."
    }
  ]
}

Create Post

Creates a new post within your project's CMS. A title is required. If a slug is not provided, one will be automatically generated from the title.

POST /cms/post/create

Body Parameters

Parameter	Type	Required	Description
`title`	String	Yes	The title of the post.
`slug`	String	Optional	The URL-friendly identifier. Auto-generated from title if omitted.
`content`	String	Optional	The full content of the post in a raw format (e.g., HTML, Markdown).
`author`	String	Optional	The author's identifier. Defaults to `api-user`.
`status`	String	Optional	The status of the post (e.g., `draft`, `published`). Defaults to `draft`.
`category`	Array	Optional	An array of category objects, e.g., `[{"value": "cat-slug-1"}]`.
`tag`	Array	Optional	An array of tag objects.
`seo_meta_title`	String	Optional	The title for SEO purposes.
`seo_meta_desc`	String	Optional	The description for SEO purposes.
`featured_image`	String	Optional	The URL of the featured image.
`summary`	String	Optional	A short summary of the post.
`keyword`	String	Optional	The primary keyword for SEO analysis.
...	...	Optional	Other fields like `word_count`, `image_count`, `score`, etc.

Example Request

JSON

{
  "title": "New Post via API",
  "content": "<h1>Hello World</h1><p>This is the content of my new post.</p>",
  "status": "draft",
  "author": "user-123",
  "category": [{"value": "tech"}],
  "keyword": "API"
}

Example Success Response (200)

JSON

{
    "success": true,
    "message": "New Post Created.",
    "data": {
        "id": "newly_generated_post_id",
        "slug": "new-post-via-api",
        "project_id": "your_project_id"
    }
}

Update Post

Updates an existing post's data. You must provide the post_id.

POST /cms/post/update

Body Parameters

Parameter	Type	Required	Description
`post_id`	String	Yes	The unique identifier of the post to update.
`title`	String	Optional	The new title of the post.
`slug`	String	Optional	The new URL-friendly identifier.
`content`	String	Optional	The new full content of the post.
...	...	Optional	Any other parameter from the "Create Post" endpoint can be provided to update its value.

Example Request

JSON

{
  "post_id": "existing_post_id",
  "title": "An Updated Post Title",
  "status": "published",
  "first_published": 1678886400
}

Example Success Response (200)

JSON

{
    "success": true,
    "message": "Post Updated.",
    "data": {
        "id": "existing_post_id",
        "slug": "an-updated-post-title",
        "project_id": "your_project_id"
    }
}

Delete Post

Deletes a post from your project. This action is irreversible.

POST /cms/post/delete

Body Parameters

Parameter	Type	Required	Description
`post_id`	String	Yes	The unique identifier of the post to delete.

Example Request

JSON

{
  "post_id": "post_id_to_delete"
}

Example Success Response (200)

JSON

{
    "success": true,
    "message": "Posts Deleted",
    "data": {
        "deleted_post_id": "post_id_to_delete",
        "project_id": "your_project_id"
    }
}

Publish Post

Changes the status of one or more draft posts to "published" and adds them to the publishing queue. If a post is already published, it will be ignored.

POST /cms/post/publish

Body Parameters

Parameter	Type	Required	Description
`post_id`	Array of Strings	Yes	An array of unique identifiers for the posts to publish.

Example Request

JSON

{
  "post_id": ["post_id_1", "post_id_2"]
}

Example Success Response (200)

JSON

{
    "success": true,
    "message": "Posts published successfully. 1 post(s) were already published. 1 post(s) added to publish queue.",
    "data": {
        "published_post_ids": [
            "post_id_2"
        ],
        "already_published_post_ids": [
            "post_id_1"
        ],
        "queue_id": "generated_queue_id",
        "project_id": "your_project_id",
        "first_published": 1678887000
    }
}

Unpublish Post

Changes a post's status from "published" back to "draft".

POST /cms/post/unpublish

Body Parameters

Parameter	Type	Required	Description
`post_id`	String	Yes	The unique identifier of the post to unpublish.

Example Request

JSON

{
  "post_id": "published_post_id"
}

Example Success Response (200)

JSON

{
    "success": true,
    "message": "Post unpublished successfully.",
    "data": {
        "post_id": "published_post_id",
        "project_id": "your_project_id"
    }
}