Content API References

Get All Collections

URL: https://api.gradual-api.com/public-api/v1/collections

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200

Note: The collections are returned in order of creation date, with the most recently created collections appearing first.

Response Example:

{
    "size": 1,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "collectionId": "63e293d17efa0788a97273fe",
            "collectionName": "Collection Name",
            "collectionVisibility": "Visible",
            "collectionUrl": "https://elc.gradual/home/collections/collection-name",
            "collectionCoverUrl": "https://abc.cloudfront.net/uploads/test/Collection-Name-fd0ffeb0-195e-491e-9eea-ae351f9914d8-1676390983173.png",
            "collectionSlug": "collection-name",
            "collectionUpdatedAt": "2025-08-14T12:39:31.259Z",
            "collectionContent": [
                {
                    "type": "video",
                    "id": "63d40ad685f10b97ffa7feae",
                    "title": "Video Title"
                },
                {
                    "type": "blog",
                    "id": "6266772cfffad41e5be35862",
                    "title": "Article Title"
                }
            ]
        }
    ]
}

Get All Videos

URL: https://api.gradual-api.com/public-api/v1/videos

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
fromDate, string, optional, format: YYYY-MM-DD, date will be padded to the start of the day. If a fromDate is specified, the response will include videos with a created time later than 00:00 of the provided fromDate.
toDate, string, optional, format: YYYY-MM-DD, date will be padded to the end of the day. Similarly, if a toDate is specified, the response will include videos with a created time earlier than 23:59 of the provided toDate.

Note: The videos are returned in order of creation date, with the most recently created videos appearing first.

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "videoId": "654180e3566f8d5a7fb49e86",
            "videoTitle": "Video Title",
            "videoDescription": "Video Description",
            "videoCreatedAt": "2023-10-31T22:34:11.099Z",
            "videoSlug": "video-title",
            "videoUrl": "https://www.youtube.com/watch?v=_Z1mwUosYU",
            "videoThumbnailUrl": "https://abc.cloudfront.net/uploads/test/Video-Title-fd0ffeb0-195e-491e-9eea-ae351f9914d8-1676390983173.png",
            "videoDuration": 120,
            "videoTags": [
                "tag1",
                "tag2"
            ],
            "spaces": [
                "Space 1",
                "Space 2"
            ],
            "access": "Public",
            "ownership": "Community"
        },
        {
            "videoId": "64adee61dc5dfe85abf9ae3e",
            "videoTitle": "Video Title",
            "videoDescription": "Video Description",
            "videoCreatedAt": "2023-10-31T22:34:11.099Z",
            "videoSlug": "video-title",
            "videoUrl": "https://www.youtube.com/watch?v=_Z1mwUYgwU",
            "videoThumbnailUrl": "https://abc.cloudfront.net/uploads/test/Video-Title-fd0ffeb0-195e-491e-9eea-ae351f9914d8-1676390983173.png",
            "videoDuration": 120,
            "videoTags": [],
            "spaces": [],
            "access": "Public",
            "ownership": "VIP Club"
        }
    ]
}

Get All Blogs

URL: https://api.gradual-api.com/public-api/v1/blogs

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
fromDate, string, optional, format: YYYY-MM-DD, date will be padded to the start of the day. If a fromDate is specified, the response will include blogs with a created time later than 00:00 of the provided fromDate.
toDate, string, optional, format: YYYY-MM-DD, date will be padded to the end of the day. Similarly, if a toDate is specified, the response will include blogs with a created time earlier than 23:59 of the provided toDate.

Note: The blogs are returned in order of creation date, with the most recently created blogs appearing first.

Response Example:

{
    "size": 1,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "blogId": "654180e3566f8d5a7fb49e86",
            "blogTitle": "Blog Title",
            "blogSubTitle": "Blog Sub Title",
            "blogAuthor": "Blog Author1, Blog Author2",
            "blogSummary": "Blog Summary",
            "blogContent": "Blog Content",
            "blogCategory": "Blog Category",
            "blogCreatedAt": "2023-10-31T22:34:11.099Z",
            "blogSlug": "blog-title",
            "blogCoverUrl": "https://abc.cloudfront.net/uploads/test/Video-Title-fd0ffeb0-195e-491e-9eea-ae351f9914d8-1676390983173.png",
            "blogTags": [
                "tag1"
            ],
            "spaces": [
                "Space 1"
            ],
            "access": "Public",
            "ownership": "Community"
        }
    ]
}

Get All Podcasts

URL: https://api.gradual-api.com/public-api/v1/podcasts

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
fromDate, string, optional, format: YYYY-MM-DD, date will be padded to the start of the day. If a fromDate is specified, the response will include podcasts with a created time later than 00:00 of the provided fromDate.
toDate, string, optional, format: YYYY-MM-DD, date will be padded to the end of the day. Similarly, if a toDate is specified, the response will include podcasts with a created time earlier than 23:59 of the provided toDate.

Note: The podcasts are returned in order of creation date, with the most recently created podcasts appearing first.

Response Example:

{
    "size": 1,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "podcastId": "654180e3566f8d5a7fb49e86",
            "podcastTitle": "Podcast Title",
            "podcastSubTitle": "Podcast Sub Title",
            "podcastAuthor": "Podcast Author1, Podcast Author2",
            "podcastSummary": "Podcast Summary",
            "podcastContent": "Podcast Content",
            "podcastCategory": "Podcast Category",
            "podcastCreatedAt": "2023-10-31T22:34:11.099Z",
            "podcastSlug": "podcast-title",
            "podcastCoverUrl": "https://abc.cloudfront.net/uploads/test/Video-Title-fd0ffeb0-195e-491e-9eea-ae351f9914d8-1676390983173.png",
            "podcastTags": [
                "tag1"
            ],
            "spaces": [
                "Space 1"
            ],
            "access": "Public",
            "ownership": "Community"
        }
    ]
}

Get All Resources

URL: https://api.gradual-api.com/public-api/v1/resources

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
fromDate, string, optional, format: YYYY-MM-DD, date will be padded to the start of the day. If a fromDate is specified, the response will include resources with a created time later than 00:00 of the provided fromDate.
toDate, string, optional, format: YYYY-MM-DD, date will be padded to the end of the day. Similarly, if a toDate is specified, the response will include resources with a created time earlier than 23:59 of the provided toDate.

Note: The resources are returned in order of creation date, with the most recently created resources appearing first.

Response Example:

{
    "size": 1,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "resourceId": "654180e3566f8d5a7fb49e86",
            "resourceTitle": "Resource Title",
            "resourceSubTitle": "Resource Sub Title",
            "resourceAuthor": "Resource Author1, Resource Author2",
            "resourceSummary": "Resource Summary",
            "resourceContent": "Resource Content",
            "resourceCategory": "Resource Category",
            "resourceCreatedAt": "2023-10-31T22:34:11.099Z",
            "resourceSlug": "resource-title",
            "resourceCoverUrl": "https://abc.cloudfront.net/uploads/test/Video-Title-fd0ffeb0-195e-491e-9eea-ae351f9914d8-1676390983173.png",
            "resourceTags": [
                "tag1"
            ],
            "spaces": [
                "Space 1"
            ],
            "access": "Public",
            "ownership": "VIP Club"
        }
    ]
}

Get All External Contents

URL: https://api.gradual-api.com/public-api/v1/external-contents

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, number, optional, default 1
pageSize, number, optional, default 50, max 200
fromDate, string, optional, format: YYYY-MM-DD, date will be padded to the start of the day. If a fromDate is specified, the response will include external-contents with a created time later than 00:00 of the provided fromDate.
toDate, string, optional, format: YYYY-MM-DD, date will be padded to the end of the day. Similarly, if a toDate is specified, the response will include external-contents with a created time earlier than 23:59 of the provided toDate.

Note: The external-contents are returned in order of creation date, with the most recently created external-contents appearing first.

Response Example:

{
    "size": 1,
    "pageNumber": 1,
    "pageSize": 50,
    "results": [
        {
            "externalContentId": "654180e3566f8d5a7fb49e86",
            "externalContentTitle": "External Content Title",
            "externalContentSummary": "External Content Summary",
            "externalContentContent": "External Content Content",
            "externalContentCategory": "External Content Category",
            "externalContentCreatedAt": "2023-10-31T22:34:11.099Z",
            "externalContentSlug": "external-content-title",
            "externalContentCoverUrl": "https://abc.cloudfront.net/uploads/test/Video-Title-fd0ffeb0-195e-491e-9eea-ae351f9914d8-1676390983173.png",
            "externalContentLink": "https://www.google.com",
            "externalContentTags": [
                "tag1"
            ],
            "spaces": [
                "Space 1"
            ],
            "access": "Public",
            "ownership": "Community"
        }
    ]
}

Add a New Video

URL: https://api.gradual-api.com/public-api/v1/videos

HTTP Method: POST

Content type: application/json

Tier: Medium

Request Body Parameters:

title, string, required, video title (1–300 characters), must be unique
videoUrl, string, required, must be a valid URL pointing to the video file
posterUrl, string, required, must be a valid URL pointing to a thumbnail image (must be 16:9 aspect ratio)
duration, string, required, video length in HH:MM:SS, MM:SS, or total seconds format
authorEmail, string, optional, email of an existing user to attribute as the video author
tags, string, optional, comma-separated list of tag names (tags will be created if they don't exist)
publish, boolean, optional, whether to publish the video immediately (defaults to false)
collection, string, optional, name of an existing collection to add the video to
summary, string, optional, video description
transcript, string, optional, video transcript text

Request Body Example:

{
    "title": "Getting Started with Gradual",
    "videoUrl": "https://example.com/videos/getting-started.mp4",
    "posterUrl": "https://example.com/thumbnails/getting-started.jpg",
    "duration": "12:34",
    "authorEmail": "[email protected]",
    "tags": "Tutorial, Getting Started",
    "publish": true,
    "collection": "Onboarding",
    "summary": "A walkthrough of the Gradual platform for new users.",
    "transcript": "Welcome to Gradual..."
}

Response Example:

{
    "videoId": "6553ce608b3f645e79d95034",
    "videoTitle": "Getting Started with Gradual",
    "videoDescription": "A walkthrough of the Gradual platform for new users.",
    "videoDuration": 754,
    "videoThumbnailUrl": "https://s3.amazonaws.com/uploads/tenant/thumbnail.jpg",
    "videoUrl": "https://example.com/videos/getting-started.mp4",
    "videoCreatedAt": "2024-11-14T10:30:00.000Z",
    "videoSlug": "getting-started-with-gradual",
    "videoTags": ["Tutorial", "Getting Started"],
    "videoTranscript": "Welcome to Gradual..."
}

Notes:

The posterUrl image must have a 16:9 aspect ratio, otherwise the request will be rejected. The image is downloaded and re-hosted on our servers.
The duration field accepts multiple formats: HH:MM:SS (e.g. 1:12:34), MM:SS (e.g. 12:34), or total seconds as a plain number (e.g. 754).
If authorEmail is provided but no matching user is found, the video will still be created without an author.
A video with a duplicate title will be rejected with a 400 error.
If collection is provided but does not match an existing collection name, the request will be rejected with a 400 error.

Clubs

Forum