Developers
IdeaTopic developer API
Publish posts to IdeaTopic communities from your own system, one at a time or in bulk, and read, edit or delete what you published.
- Base URL
- https://api.ideatopic.com/developer/v1
- Version
- v1
1. What the API is for
The API lets a system you run publish text posts into IdeaTopic communities under one member account: a course site posting its announcements, a newsroom posting its explainers, a tool importing an archive of questions. Posts made this way appear on that account’s profile and in the community they were sent to, exactly like posts written in the app. The API publishes and manages your own posts; it does not read other members’ posts or act on their behalf.
| Method | Path | What it does |
|---|---|---|
| GET | /me | The key, the account it publishes as, its limits and today’s usage |
| GET | /topics | Post kinds, topic values and field length limits |
| GET | /groups | The communities a post can be published in |
| POST | /posts | Publish one post |
| POST | /posts/bulk | Publish several posts in one request |
| GET | /posts | List the posts this key published |
| GET | /posts/:id | Read one post with its current stats |
| PATCH | /posts/:id | Edit a post |
| DELETE | /posts/:id | Delete a post |
2. Getting access
There is no self-service sign-up. Keys are issued by the IdeaTopic team, and a key does not work until the team has verified it.
To ask for one, write to us through the contact page and say:
- which IdeaTopic account should publish the posts, and
- what you plan to post.
A key publishes as one member account. Its posts appear on that profile and follow the same community rules as posts made in the app.
Keep the key on a server. Never ship it in a browser or a mobile app, where anyone can read it. If it leaks, ask us to rotate it.
3. Authentication
Send the key with every request, in the Authorization header:
Authorization: Bearer itk_live_YOUR_KEYIf your client cannot set that header, X-API-Key is accepted instead:
X-API-Key: itk_live_YOUR_KEYRequests and responses are JSON. Send Content-Type: application/json with any request that has a body.
A successful response wraps its result in data:
{
"data": { }
}A failed one carries an error with a stable code and a readable message, alongside an HTTP status. Branch on the code, not the message. Every code is listed under Errors.
{
"error": {
"code": "GROUP_NOT_FOUND",
"message": "No community matches that groupId or groupSlug."
}
}4. Quick start
First check the key. GET /me returns the key’s name and status, its scopes, the account it publishes as, its limits and today’s usage.
curl https://api.ideatopic.com/developer/v1/me \
-H "Authorization: Bearer itk_live_YOUR_KEY"{
"data": {
"name": "Course site importer",
"status": "active",
"scopes": ["groups:read", "posts:read", "posts:write"],
"publishesAs": { "name": "Example Academy", "uniqueName": "example-academy" },
"limits": { "requestsPerMinute": 30, "postsPerDay": 100, "postsPerBulkRequest": 25 },
"today": { "requests": 4, "posts": 2, "postsRemaining": 98 }
}
}Then publish one post. Pick a community with GET /groups and send its slug or id with the text.
curl -X POST https://api.ideatopic.com/developer/v1/posts \
-H "Authorization: Bearer itk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupSlug": "computer-science",
"title": "How we teach recursion in week three",
"content": "Most students meet recursion as a definition. We start with a call stack drawn on paper instead.",
"kind": "discussion",
"topics": ["Computer"],
"externalId": "article-1042"
}'The response is the published post, including its public url. The ids, names and counts in the examples on this page are illustrative.
5. Publishing one post
POST /posts publishes one post. It needs the posts:write scope.
| Field | Required | Notes |
|---|---|---|
| groupId or groupSlug | Required | The community to publish in. Send one of the two; both come from GET /groups. |
| content | Required | The text of the post. Up to 10,000 characters. |
| title | Optional | Up to 200 characters. |
| kind | Optional | question, discussion, resource or help. Defaults to discussion. |
| topics | Optional | A list of values from GET /topics. Up to 3 are kept. |
| externalId | Optional | Your own reference for the post. Up to 120 characters. Makes the request safe to retry. |
curl -X POST https://api.ideatopic.com/developer/v1/posts \
-H "Authorization: Bearer itk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"groupSlug": "computer-science",
"title": "How we teach recursion in week three",
"content": "Most students meet recursion as a definition. We start with a call stack drawn on paper instead.",
"kind": "discussion",
"topics": ["Computer"],
"externalId": "article-1042"
}'const response = await fetch('https://api.ideatopic.com/developer/v1/posts', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.IDEATOPIC_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
groupSlug: 'computer-science',
title: 'How we teach recursion in week three',
content:
'Most students meet recursion as a definition. We start with a call stack drawn on paper instead.',
kind: 'discussion',
topics: ["Computer"],
externalId: 'article-1042',
}),
});
const body = await response.json();
if (!response.ok) {
throw new Error(`${body.error.code}: ${body.error.message}`);
}
console.log(body.duplicate ? 'Already published' : 'Published', body.data.url);A new post returns 201 with the post and duplicate: false.
{
"data": {
"id": "6741c0f2a9d4e31b7c5f0a12",
"externalId": "article-1042",
"title": "How we teach recursion in week three",
"content": "Most students meet recursion as a definition. We start with a call stack drawn on paper instead.",
"kind": "discussion",
"topics": ["Computer"],
"group": { "id": "66f0a1b2c3d4e5f6a7b8c9d0", "slug": "computer-science", "name": "Computer Science" },
"status": "active",
"underReview": false,
"url": "https://www.ideatopic.com/community/post/how-we-teach-recursion-in-week-three",
"stats": { "likes": 0, "comments": 0, "views": 0, "shares": 0 },
"createdAt": "2026-11-19T09:30:00.000Z",
"updatedAt": "2026-11-19T09:30:00.000Z"
},
"duplicate": false
}Retrying safely with externalId
If the externalId was already used by this key, nothing new is published. The response is 200 with the existing post and duplicate: true. So when a request times out and you do not know whether it arrived, send it again with the same externalId.
{
"data": { "id": "6741c0f2a9d4e31b7c5f0a12", "externalId": "article-1042", "…": "the post as first published" },
"duplicate": true
}The Post object
| Field | Type | Notes |
|---|---|---|
| id | string | The post id. |
| externalId | string or null | Your own reference, if you sent one. |
| title | string | The title, if the post has one. |
| content | string | The text of the post. |
| kind | string | question, discussion, resource or help. |
| topics | string[] | The topics kept on the post. |
| group | object | The community it was published in: { id, slug, name }. |
| status | string | The post’s current status. |
| underReview | boolean | True when the post is published but queued for a moderator. |
| url | string | The public web address of the post. |
| stats | object | { likes, comments, views, shares }. |
| createdAt | string | When the post was published. |
| updatedAt | string | When the post was last changed. |
6. Publishing in bulk
POST /posts/bulk publishes several posts in one request. It needs the posts:write scope. The body is { "posts": [ … ] }, where each item is the same object POST /posts takes. A request can hold up to the key’s postsPerBulkRequest, which is 25 by default.
- Each post is judged on its own. One failing does not stop the others.
- Results come back in the order the posts were sent, each with its index.
- Each result has a
statusofcreated,duplicateorfailed. Created and duplicate results carry thepost; failed ones carry anerrorwith a code and message. - If the valid posts in a batch are more than what is left of the daily allowance, the whole request is refused with
429 DAILY_LIMITand nothing is published. - Running a batch again publishes nothing twice, as long as its posts carry
externalIds. - The same
externalIdtwice inside one request makes that item fail withDUPLICATE_IN_REQUEST.
A full request and response
Three posts: one that was already published in an earlier run, one that is new, and one that names a community that does not exist.
curl -X POST https://api.ideatopic.com/developer/v1/posts/bulk \
-H "Authorization: Bearer itk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"posts": [
{
"groupSlug": "computer-science",
"title": "How we teach recursion in week three",
"content": "Most students meet recursion as a definition. We start with a call stack drawn on paper instead.",
"externalId": "article-1042"
},
{
"groupSlug": "computer-science",
"title": "Which sorting algorithm should a beginner learn first?",
"content": "We have tried starting with bubble sort and with insertion sort. What worked for you?",
"kind": "question",
"externalId": "article-1043"
},
{
"groupSlug": "no-such-group",
"content": "This one names a community that does not exist.",
"externalId": "article-1044"
}
]
}'The request itself succeeds with 200, and each post reports its own outcome:
{
"data": {
"results": [
{
"index": 0,
"status": "duplicate",
"post": { "id": "6741c0f2a9d4e31b7c5f0a12", "externalId": "article-1042", "…": "the existing post" }
},
{
"index": 1,
"status": "created",
"post": {
"id": "6741c0f2a9d4e31b7c5f0a13",
"externalId": "article-1043",
"title": "Which sorting algorithm should a beginner learn first?",
"content": "We have tried starting with bubble sort and with insertion sort. What worked for you?",
"kind": "question",
"topics": [],
"group": { "id": "66f0a1b2c3d4e5f6a7b8c9d0", "slug": "computer-science", "name": "Computer Science" },
"status": "active",
"underReview": false,
"url": "https://www.ideatopic.com/community/post/which-sorting-algorithm-should-a-beginner-learn-first",
"stats": { "likes": 0, "comments": 0, "views": 0, "shares": 0 },
"createdAt": "2026-11-19T09:31:00.000Z",
"updatedAt": "2026-11-19T09:31:00.000Z"
}
},
{
"index": 2,
"status": "failed",
"error": { "code": "GROUP_NOT_FOUND", "message": "No community matches that groupId or groupSlug." }
}
],
"summary": { "total": 3, "created": 1, "duplicate": 1, "failed": 1 }
}
}const response = await fetch('https://api.ideatopic.com/developer/v1/posts/bulk', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.IDEATOPIC_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ posts }), // up to your key's postsPerBulkRequest
});
const body = await response.json();
if (!response.ok) {
// The whole request was refused: nothing in it was published.
throw new Error(`${body.error.code}: ${body.error.message}`);
}
for (const result of body.data.results) {
if (result.status === 'failed') {
console.error(`Post ${result.index} failed: ${result.error.code}`);
}
}
console.log(body.data.summary); // { total, created, duplicate, failed }Import safely
To move an archive in without publishing anything twice:
- Give every post an
externalId, such as the id it has in your own system. - Send in batches no larger than your key’s
postsPerBulkRequest, and keep the day’s total withinpostsRemainingfromGET /me. - If anything fails (a timeout, a
429, a crash on your side), run the same import again. Posts that already went in come back asduplicate; only the missing ones are published.
const API = 'https://api.ideatopic.com/developer/v1';
const headers = {
Authorization: `Bearer ${process.env.IDEATOPIC_API_KEY}`,
'Content-Type': 'application/json',
};
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
// `posts` is your own list. Every item carries an externalId.
async function importPosts(posts) {
const me = await (await fetch(`${API}/me`, { headers })).json();
const size = me.data.limits.postsPerBulkRequest;
const failed = [];
for (let start = 0; start < posts.length; start += size) {
const batch = posts.slice(start, start + size);
const response = await fetch(`${API}/posts/bulk`, {
method: 'POST',
headers,
body: JSON.stringify({ posts: batch }),
});
const body = await response.json();
if (response.status === 429 && body.error.code === 'RATE_LIMITED') {
await sleep(body.error.retryAfter);
start -= size; // send the same batch again
continue;
}
if (!response.ok) {
// DAILY_LIMIT and anything else: stop here. Nothing in this batch was
// published, and running the import again later picks up where it stopped.
throw new Error(`${body.error.code}: ${body.error.message}`);
}
for (const result of body.data.results) {
if (result.status === 'failed') {
failed.push({ externalId: batch[result.index].externalId, error: result.error });
}
}
}
return failed; // fix these, then run the import again
}7. Reading, editing and deleting
A key can only read, edit or delete posts it published itself. Posts the same account wrote in the app are not visible to it. Wherever a path takes :id, you can send either the post id or your own externalId.
List your posts
GET /posts returns the posts this key published, newest first. It needs the posts:read scope. limit is 25 by default and at most 100. When nextCursor is not null, pass it back as cursor to get the next page.
curl "https://api.ideatopic.com/developer/v1/posts?limit=25" \
-H "Authorization: Bearer itk_live_YOUR_KEY"{
"data": {
"posts": [ { "id": "6741c0f2a9d4e31b7c5f0a13", "…": "a Post" } ],
"nextCursor": "A_VALUE_TO_PASS_BACK"
}
}Read one post
GET /posts/:id returns the post with its current stats: likes, comments, views and shares.
curl https://api.ideatopic.com/developer/v1/posts/article-1042 \
-H "Authorization: Bearer itk_live_YOUR_KEY"Edit a post
PATCH /posts/:id takes any of title, content, kind and topics, and returns the updated post. The public URL does not change.
curl -X PATCH https://api.ideatopic.com/developer/v1/posts/article-1042 \
-H "Authorization: Bearer itk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "title": "How we teach recursion in the third week" }'Delete a post
DELETE /posts/:id removes the post.
curl -X DELETE https://api.ideatopic.com/developer/v1/posts/article-1042 \
-H "Authorization: Bearer itk_live_YOUR_KEY"{
"data": { "id": "6741c0f2a9d4e31b7c5f0a12", "deleted": true }
}8. Communities and topics
Communities
Every post is published in a community. GET /groups lists the ones a post can be published in. It needs the groups:read scope. Filter with q (a search term) and section; limit is 50 by default and at most 200.
curl "https://api.ideatopic.com/developer/v1/groups?q=computer&limit=10" \
-H "Authorization: Bearer itk_live_YOUR_KEY"{
"data": [
{
"id": "66f0a1b2c3d4e5f6a7b8c9d0",
"slug": "computer-science",
"name": "Computer Science",
"section": "Technology",
"members": 128
}
]
}Use the id as groupId or the slug as groupSlug when you publish. You can also browse the same communities on the groups page.
Kinds and topics
GET /topics returns the post kinds, the topic values a post can carry, and the field length limits. Read the values from this endpoint rather than hard-coding them.
{
"data": {
"kinds": ["question", "discussion", "resource", "help"],
"topics": ["…"],
"limits": { "titleMax": 200, "contentMax": 10000, "externalIdMax": 120 }
}
}kind defaults to discussion. A post can be sent with a list of topics; up to 3 are kept.
9. Limits
These are the defaults. Limits are set per key by the team, and GET /me shows the ones that apply to yours, with today’s usage.
| Limit | Default | When exceeded |
|---|---|---|
| Requests per minute | 30 | 429 RATE_LIMITED |
| Posts per UTC day | 100 | 429 DAILY_LIMIT |
| Posts per bulk request | 25 | 400 TOO_MANY_POSTS |
- A bulk request counts as one request.
- Refused and duplicate posts do not use the daily allowance.
- Every response carries an
X-RateLimit-Limitheader. RATE_LIMITEDcomes with aRetry-Afterheader and the same number of seconds asretryAfterin the error. Wait that long, then send the request again.DAILY_LIMITcarrieslimit,remainingandresetsAt. The day is counted in UTC.
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 30
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Try again shortly.",
"retryAfter": 12
}
}{
"error": {
"code": "DAILY_LIMIT",
"message": "The daily post allowance has been reached.",
"limit": 100,
"remaining": 0,
"resetsAt": "2026-11-20T00:00:00.000Z"
}
}10. Errors
Every error has the same shape: an HTTP status, and a body with error.code and error.message. In a bulk request, a post that fails carries the same { code, message } in its own result.
| Code | Status | Meaning |
|---|---|---|
| NO_KEY | 401 | The request carried no API key. |
| INVALID_KEY | 401 | The key is not one we issued. |
| KEY_NOT_VERIFIED | 403 | The key exists but the team has not verified it yet. |
| KEY_SUSPENDED | 403 | The key has been suspended. |
| SCOPE_MISSING | 403 | The key does not have the scope this endpoint needs. |
| ACCOUNT_INACTIVE | 403 | The account the key publishes as is not active. |
| EMAIL_UNVERIFIED | 403 | The publishing account has not confirmed its email. |
| RATE_LIMITED | 429 | Too many requests this minute. Wait for the time in Retry-After. |
| DAILY_LIMIT | 429 | The daily post allowance would be exceeded. Nothing was published. |
| GROUP_REQUIRED | 400 | Neither groupId nor groupSlug was sent. |
| GROUP_NOT_FOUND | 404 | No community matches the groupId or groupSlug. |
| CONTENT_REQUIRED | 400 | content is missing or empty. |
| CONTENT_TOO_LONG | 400 | content is longer than 10,000 characters. |
| TITLE_TOO_LONG | 400 | title is longer than 200 characters. |
| INVALID_KIND | 400 | kind is not one of the values from GET /topics. |
| INVALID_TOPICS | 400 | topics is not a list of values from GET /topics. |
| INVALID_EXTERNAL_ID | 400 | externalId is not valid, or is longer than 120 characters. |
| LINK_REFUSED | 400 | A link in the post is not allowed. The error names the link. |
| CONTENT_REFUSED | 400 | The wording breaks the community rules. |
| INVALID_BODY | 400 | The request body is not the JSON this endpoint expects. |
| TOO_MANY_POSTS | 400 | A bulk request held more posts than the key allows per request. |
| DUPLICATE_IN_REQUEST | Per item (bulk) | The same externalId appears twice in one bulk request. That item fails. |
| POST_NOT_FOUND | 404 | No post published by this key has that id or externalId. |
| INVALID_CURSOR | 400 | cursor is not a value returned as nextCursor. |
| NOTHING_TO_UPDATE | 400 | A PATCH carried none of title, content, kind or topics. |
| NOT_FOUND | 404 | There is no endpoint at that path. |
| SERVER_ERROR | 500 | Something failed on our side. Retry later; with an externalId the retry is safe. |
11. Rules and good practice
Content rules
- This version is text only. Images and files cannot be attached.
- Links are checked by the same rules as the app. A refused link returns
400 LINK_REFUSEDwith the offendinglink. - Wording that breaks the community rules returns
400 CONTENT_REFUSED. - A post can be published and still be queued for a moderator.
underReviewon the post says so. - API posts do not send push notifications to members.
{
"error": {
"code": "LINK_REFUSED",
"message": "A link in this post is not allowed.",
"link": "https://example.com/refused"
}
}Good practice
- Send an
externalIdwith every post. It makes retries safe and lets you fetch, edit and delete by your own reference. - Keep the key on a server and out of source control. Ask for a rotation if it may have leaked.
- Call
GET /mebefore a large run to see what is left of the day’s allowance. - Read kinds and topics from
GET /topicsand communities fromGET /groupsinstead of hard-coding them. - Handle errors by
code. Messages are written for people to read.
12. Versioning
The path carries the version: /developer/v1. Version 1 will not change shape. Additions arrive as new fields or new endpoints, so write clients that ignore fields they do not recognise.
13. Contact
To ask for a key, have one rotated, ask about its limits, or report a problem with the API, write to the team through the contact page. Say which account the key publishes as, and include the error code if there is one. Never include the key itself in a message.