Curator API: Sources
The /v1/sources endpoints let you list, add, and delete the sources that pull posts into your feeds, such as an Instagram account or a hashtag. Every request needs your API key, and your plan must include API access. Only HTTPS is supported.
Authentication
Send your Curator API key (find it in the Curator Dashboard) in one of three ways: as a query string (?api_key=API_KEY), as a Basic auth header with the API key as the username, or as a Bearer token (Authorization: Bearer API_KEY). The key decides which account you are working in; you can only see and change that account's sources.
Endpoints
Method and path | What it does |
|---|---|
| Lists the sources in your account, optionally for one feed. |
| Adds a source to a feed and loads its first posts. |
| Deletes a source. |
To pause or resume a source, use the Curator Dashboard.
List sources
curl "https://api.curator.io/v1/sources?api_key=API_KEY&feed_id=FEED_API_ID"Parameter | Description |
|---|---|
| Only sources in this feed, by the feed's API ID. If no feed in your account has that API ID, the filter is ignored and every source is returned. |
Returns a JSON array of source objects, with no wrapper and no pagination.
Add a source
curl -X POST "https://api.curator.io/v1/sources?api_key=API_KEY" \
-d "feed_id=FEED_API_ID" \
-d "source_type=16" \
-d "tag=https://www.curator.io/blog/rss"Parameter | Description |
|---|---|
| The API ID of the feed to add the source to. The public key is not accepted here. |
| The source type ID, an integer from the source types table below. |
| What to pull posts from, up to 200 characters: an account handle, hashtag, search term, or URL, depending on the source type. |
| Display name for the source. When left out, Curator names the source for you. |
| URL of an image to show as the author image on this source's posts. |
Adding a source loads its first posts straight away, so the request can take a few seconds. On success, the response is the new source object with a response field added:
{
"id": "SOURCE_API_ID",
"feed_id": "FEED_API_ID",
"source_type": 16,
"tag": "https://www.curator.io/blog/rss",
"status": "active",
...
"response": { "success": true, "message": "12 posts were added to your feed" }
}If the first load fails, the source is removed again and the response is a 200 with an error body instead of a source object:
{ "success": false, "error": true, "message": "Loading posts failed with - REASON" }Always check for "error": true before treating the source as added. When the failure is caused by an expired connection, the message is Loading posts failed: connection is not longer valid and the connection is disabled until you reconnect it in the Curator Dashboard.
Delete a source
curl -X DELETE "https://api.curator.io/v1/sources/SOURCE_API_ID?api_key=API_KEY"source_id is the source's id from a source object. A successful delete returns:
{ "success": true, "message": "Source deleted" }Source types
Source types marked "Needs a connection" only work after you connect that network's account under Connections in the Curator Dashboard. Without one, adding the source returns a 422 with a link to the Connections page.
ID | Source type | Needs a connection |
|---|---|---|
1 | Twitter Hashtag | Yes |
3 | Twitter User | Yes |
5 | Facebook Page | Yes |
7 | Pinterest User | No |
9 | Flickr Hashtag | No |
10 | YouTube Hashtag | No |
11 | Tumblr Hashtag | No |
13 | YouTube Channel | No |
14 | Tumblr User | No |
15 | Flickr User | No |
16 | RSS | No |
27 | Flickr Album | No |
28 | Vimeo Tag | No |
32 | Glassdoor Employer Reviews | No |
33 | Instagram Business Account | Yes |
34 | Instagram Account | Yes |
35 | YouTube Playlist | No |
38 | Instagram Business Hashtag | Yes |
39 | Yelp Business Reviews | No |
40 | DeviantArt User Gallery | No |
41 | Behance Project | No |
43 | Slack Channel Feed | Yes |
45 | Giphy Search | No |
46 | Instagram Business Mention | Yes |
47 | Instagram Stories | Yes |
48 | Reddit Subreddit Feed | Yes |
49 | Reddit User Feed | Yes |
51 | TikTok User Videos | Yes |
54 | Instagram Tagged Business / Collab Posts | Yes |
55 | Facebook Page Mention | Yes |
56 | LinkedIn Company Page | No |
57 | TikTok Hashtag | Yes |
58 | Google Reviews (Lite) | No |
59 | Google Reviews | No |
60 | Threads User | Yes |
61 | Threads Mentions | Yes |
62 | LinkedIn Profile Page | No |
Some source types also depend on your plan, such as TikTok Hashtag, Google Reviews, and LinkedIn, which have their own limits.
Source object
Field | Description |
|---|---|
| The source's API ID (a UUID). Use it to delete the source. |
| API ID of the feed the source belongs to. |
| API ID of the connection the source uses, or |
| The source type ID and the ID of its network. |
| The handle, hashtag, search term, or URL the source pulls from. |
| Display name of the source. |
|
|
| How often the source checks for new posts, in minutes. |
| Date of the oldest post the source has loaded. |
| Number of posts the source has added, and how many times it has failed to update. |
| Author image used on this source's posts, when set. |
| Details of the social account behind the source, when Curator has them. |
| Author name, handle, and link that replace the original values on this source's posts, when set. |
Errors
Status | When | Body |
|---|---|---|
401 | The API key is missing or not valid. |
|
403 | Your plan does not include API access, you have reached a source limit, the source type is not on your plan, or your subscription is paused. |
|
404 | Delete only: no source with that ID in your account. |
|
422 | A required parameter is missing or invalid, the feed or source type was not found, the source type is not active, or the source type needs a connection you have not added. |
|
429 | When rate limiting is enabled, more than 60 requests per minute. |
|