Projects
Create a project
Create a new epic (referred to externally as a “Project”) in a workspace (team_id).
Specify essential properties such as the title, list ID (status), and optional fields
like icon, content, due date, priority, and owner.
Customize the epic’s icon and assign roles to team members.
This endpoint enables breaking down projects into smaller tasks (cards) for more
effective planning and progress tracking.
POST
/
{team_id}
/
epics
Create a new epic
curl --request POST \
--url https://api.superthread.com/v1/{team_id}/epics \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "<string>",
"list_id": "114",
"content": "<string>",
"content_format": "html",
"schema": 1,
"start_date": 1608742037016,
"due_date": 1608742037016,
"members": [
{
"user_id": "u-dsu0j19"
}
],
"owner_id": "<string>",
"priority": 1
}
'import requests
url = "https://api.superthread.com/v1/{team_id}/epics"
payload = {
"title": "<string>",
"list_id": "114",
"content": "<string>",
"content_format": "html",
"schema": 1,
"start_date": 1608742037016,
"due_date": 1608742037016,
"members": [{ "user_id": "u-dsu0j19" }],
"owner_id": "<string>",
"priority": 1
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: '<string>',
list_id: '114',
content: '<string>',
content_format: 'html',
schema: 1,
start_date: 1608742037016,
due_date: 1608742037016,
members: [{user_id: 'u-dsu0j19'}],
owner_id: '<string>',
priority: 1
})
};
fetch('https://api.superthread.com/v1/{team_id}/epics', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.superthread.com/v1/{team_id}/epics",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'title' => '<string>',
'list_id' => '114',
'content' => '<string>',
'content_format' => 'html',
'schema' => 1,
'start_date' => 1608742037016,
'due_date' => 1608742037016,
'members' => [
[
'user_id' => 'u-dsu0j19'
]
],
'owner_id' => '<string>',
'priority' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.superthread.com/v1/{team_id}/epics"
payload := strings.NewReader("{\n \"title\": \"<string>\",\n \"list_id\": \"114\",\n \"content\": \"<string>\",\n \"content_format\": \"html\",\n \"schema\": 1,\n \"start_date\": 1608742037016,\n \"due_date\": 1608742037016,\n \"members\": [\n {\n \"user_id\": \"u-dsu0j19\"\n }\n ],\n \"owner_id\": \"<string>\",\n \"priority\": 1\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.superthread.com/v1/{team_id}/epics")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"<string>\",\n \"list_id\": \"114\",\n \"content\": \"<string>\",\n \"content_format\": \"html\",\n \"schema\": 1,\n \"start_date\": 1608742037016,\n \"due_date\": 1608742037016,\n \"members\": [\n {\n \"user_id\": \"u-dsu0j19\"\n }\n ],\n \"owner_id\": \"<string>\",\n \"priority\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.superthread.com/v1/{team_id}/epics")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"title\": \"<string>\",\n \"list_id\": \"114\",\n \"content\": \"<string>\",\n \"content_format\": \"html\",\n \"schema\": 1,\n \"start_date\": 1608742037016,\n \"due_date\": 1608742037016,\n \"members\": [\n {\n \"user_id\": \"u-dsu0j19\"\n }\n ],\n \"owner_id\": \"<string>\",\n \"priority\": 1\n}"
response = http.request(request)
puts response.read_body{
"epic": {
"id": "2700",
"type": "epic",
"team_id": "tDsu0j19",
"icon": {
"src": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"id": "<string>",
"blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj",
"color": "black",
"emoji": "thumbsup"
},
"title": "My Card",
"schema": 1,
"content": "Some card content",
"collaboration": {
"token": "<string>"
},
"list_id": "41",
"list_color": "<string>",
"list_title": "<string>",
"status": "started",
"priority": 1,
"owner_id": "uR2dws11",
"user_id": "uR2dws11",
"user_id_updated": "u2erXoQq",
"user": {
"user_id": "uDsu0j19",
"type": "user",
"source": {
"type": "oauth",
"client_id": "oczapier",
"import_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"agent_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"email_addr": "somebody@example.com",
"email_verified": false,
"on_behalf_of": "<string>"
}
},
"user_updated": {
"user_id": "uDsu0j19",
"type": "user",
"source": {
"type": "oauth",
"client_id": "oczapier",
"import_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"agent_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"email_addr": "somebody@example.com",
"email_verified": false,
"on_behalf_of": "<string>"
}
},
"start_date": 1608742037016,
"due_date": 1608742037016,
"completed_date": 1608742037016,
"time_created": 1608742037016,
"time_updated": 1608742037016,
"health_status": "on_track",
"health_status_is_stale": false,
"health_status_stale_period": 7,
"time_health_last_updated": 1608742037016,
"health_status_updated_by": "uR2dws11",
"members": [
{
"user_id": "u-dsu0j19",
"assigned_date": 1608742037016
}
],
"checklists": [
{
"id": "232",
"title": "My Checklist",
"content": "Some description",
"card_id": "32",
"user_id": "uG2sdaOn",
"time_created": 1608742037016,
"time_updated": 1608742037016,
"items": [
{
"id": "4312",
"title": "Some title",
"content": "Some description",
"checklist_id": "432",
"user_id": "u-du9saoj1",
"time_created": 1608742037016,
"time_updated": 1608742037016,
"checked": true
}
]
}
],
"checklist_order": {},
"checklist_item_order": {},
"child_cards": [
{
"title": "Create illustration for upcoming holidays",
"card_id": "42",
"user_id": "us4Fsfed",
"project_id": "3",
"board_id": "15",
"board_title": "Ideas",
"list_id": "55",
"list_title": "Done",
"list_color": "<string>",
"status": "started",
"archived": {
"user_id": "uDsu0j19",
"time_archived": 1608742037016
}
}
],
"child_card_order": {},
"linked_cards": [
{
"title": "Create illustration for upcoming holidays",
"card_id": "42",
"user_id": "42",
"project_id": "3",
"board_id": "15",
"board_title": "Ideas",
"list_id": "list 1",
"list_title": "list 1",
"status": "started",
"archived": {
"user_id": "uDsu0j19",
"time_archived": 1608742037016
},
"linked_card_type": "blocks",
"icon": {
"src": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"id": "<string>",
"blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj",
"color": "black",
"emoji": "thumbsup"
}
}
],
"archived": {
"user_id": "uDsu0j19",
"time_archived": 1608742037016
},
"archived_list": false,
"tags": [
{
"id": "u-dsu0j19",
"team_id": "u-dsu0j19",
"project_id": "5",
"name": "todo",
"slug": "todo",
"color": "blue",
"total_cards": 17
}
],
"total_comments": 3,
"total_files": 1,
"is_watching": true,
"external_links": [
{
"github_pull_request": {
"id": 123,
"number": 123,
"state": "<string>",
"title": "<string>",
"body": "<string>",
"html_url": "<string>",
"time_created": 1608742037016,
"time_updated": 1608742037016,
"time_closed": 1608742037016,
"time_merged": 1608742037016,
"head": {
"label": "<string>",
"ref": "<string>"
},
"base": {
"label": "<string>",
"ref": "<string>"
},
"draft": true,
"merged": true
},
"generic": {
"url": "<string>",
"id": "550e8400-e29b-41d4-a716-446655440000",
"display_text": "<string>",
"time_added": 1608742037016
}
}
],
"hints": [
{
"type": "tag",
"tag": {},
"relation": {
"card": {
"title": "Create illustration for upcoming holidays",
"card_id": "42",
"user_id": "us4Fsfed",
"project_id": "3",
"board_id": "15",
"board_title": "Ideas",
"list_id": "55",
"list_title": "Done",
"list_color": "<string>",
"status": "started"
},
"similarity": 0.8
}
}
],
"cover_image": {
"src": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"id": "<string>",
"blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj",
"color": "black",
"emoji": "thumbsup",
"positionY": 123
}
}
}{
"error": {
"id": "err5f744ab",
"code": 403,
"sec": "SEC:000-00014",
"message": "You do not have access to this resource",
"date": 1608742037016
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Team ID is an alphanumerical string that identifies a Team. This is externally referred to as a "Workspace".
Body
application/json
Example:
"114"
Show child attributes
Show child attributes
Maximum string length:
102400Format of the content field. When set to 'markdown', the server converts the content from GitHub Flavored Markdown to HTML before storage. Defaults to 'html'.
Available options:
html, markdown Example:
1
unix timestamp in seconds
Example:
1608742037016
unix timestamp in seconds
Example:
1608742037016
Show child attributes
Show child attributes
Required range:
0 <= x <= 4Example:
1
Show child attributes
Show child attributes
Response
epic created
Show child attributes
Show child attributes
Previous
Update a projectModify an epic (project) in a workspace (`team_id`).
Update fields such as the title, content, due date, priority, and members.
Use this endpoint to keep epic details aligned with project updates or changes.
Next
⌘I
Create a new epic
curl --request POST \
--url https://api.superthread.com/v1/{team_id}/epics \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "<string>",
"list_id": "114",
"content": "<string>",
"content_format": "html",
"schema": 1,
"start_date": 1608742037016,
"due_date": 1608742037016,
"members": [
{
"user_id": "u-dsu0j19"
}
],
"owner_id": "<string>",
"priority": 1
}
'import requests
url = "https://api.superthread.com/v1/{team_id}/epics"
payload = {
"title": "<string>",
"list_id": "114",
"content": "<string>",
"content_format": "html",
"schema": 1,
"start_date": 1608742037016,
"due_date": 1608742037016,
"members": [{ "user_id": "u-dsu0j19" }],
"owner_id": "<string>",
"priority": 1
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: '<string>',
list_id: '114',
content: '<string>',
content_format: 'html',
schema: 1,
start_date: 1608742037016,
due_date: 1608742037016,
members: [{user_id: 'u-dsu0j19'}],
owner_id: '<string>',
priority: 1
})
};
fetch('https://api.superthread.com/v1/{team_id}/epics', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.superthread.com/v1/{team_id}/epics",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'title' => '<string>',
'list_id' => '114',
'content' => '<string>',
'content_format' => 'html',
'schema' => 1,
'start_date' => 1608742037016,
'due_date' => 1608742037016,
'members' => [
[
'user_id' => 'u-dsu0j19'
]
],
'owner_id' => '<string>',
'priority' => 1
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.superthread.com/v1/{team_id}/epics"
payload := strings.NewReader("{\n \"title\": \"<string>\",\n \"list_id\": \"114\",\n \"content\": \"<string>\",\n \"content_format\": \"html\",\n \"schema\": 1,\n \"start_date\": 1608742037016,\n \"due_date\": 1608742037016,\n \"members\": [\n {\n \"user_id\": \"u-dsu0j19\"\n }\n ],\n \"owner_id\": \"<string>\",\n \"priority\": 1\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.superthread.com/v1/{team_id}/epics")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"title\": \"<string>\",\n \"list_id\": \"114\",\n \"content\": \"<string>\",\n \"content_format\": \"html\",\n \"schema\": 1,\n \"start_date\": 1608742037016,\n \"due_date\": 1608742037016,\n \"members\": [\n {\n \"user_id\": \"u-dsu0j19\"\n }\n ],\n \"owner_id\": \"<string>\",\n \"priority\": 1\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.superthread.com/v1/{team_id}/epics")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"title\": \"<string>\",\n \"list_id\": \"114\",\n \"content\": \"<string>\",\n \"content_format\": \"html\",\n \"schema\": 1,\n \"start_date\": 1608742037016,\n \"due_date\": 1608742037016,\n \"members\": [\n {\n \"user_id\": \"u-dsu0j19\"\n }\n ],\n \"owner_id\": \"<string>\",\n \"priority\": 1\n}"
response = http.request(request)
puts response.read_body{
"epic": {
"id": "2700",
"type": "epic",
"team_id": "tDsu0j19",
"icon": {
"src": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"id": "<string>",
"blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj",
"color": "black",
"emoji": "thumbsup"
},
"title": "My Card",
"schema": 1,
"content": "Some card content",
"collaboration": {
"token": "<string>"
},
"list_id": "41",
"list_color": "<string>",
"list_title": "<string>",
"status": "started",
"priority": 1,
"owner_id": "uR2dws11",
"user_id": "uR2dws11",
"user_id_updated": "u2erXoQq",
"user": {
"user_id": "uDsu0j19",
"type": "user",
"source": {
"type": "oauth",
"client_id": "oczapier",
"import_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"agent_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"email_addr": "somebody@example.com",
"email_verified": false,
"on_behalf_of": "<string>"
}
},
"user_updated": {
"user_id": "uDsu0j19",
"type": "user",
"source": {
"type": "oauth",
"client_id": "oczapier",
"import_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"agent_id": "bf1b9f76-3f95-42fc-bd7f-050b2f5f4197",
"email_addr": "somebody@example.com",
"email_verified": false,
"on_behalf_of": "<string>"
}
},
"start_date": 1608742037016,
"due_date": 1608742037016,
"completed_date": 1608742037016,
"time_created": 1608742037016,
"time_updated": 1608742037016,
"health_status": "on_track",
"health_status_is_stale": false,
"health_status_stale_period": 7,
"time_health_last_updated": 1608742037016,
"health_status_updated_by": "uR2dws11",
"members": [
{
"user_id": "u-dsu0j19",
"assigned_date": 1608742037016
}
],
"checklists": [
{
"id": "232",
"title": "My Checklist",
"content": "Some description",
"card_id": "32",
"user_id": "uG2sdaOn",
"time_created": 1608742037016,
"time_updated": 1608742037016,
"items": [
{
"id": "4312",
"title": "Some title",
"content": "Some description",
"checklist_id": "432",
"user_id": "u-du9saoj1",
"time_created": 1608742037016,
"time_updated": 1608742037016,
"checked": true
}
]
}
],
"checklist_order": {},
"checklist_item_order": {},
"child_cards": [
{
"title": "Create illustration for upcoming holidays",
"card_id": "42",
"user_id": "us4Fsfed",
"project_id": "3",
"board_id": "15",
"board_title": "Ideas",
"list_id": "55",
"list_title": "Done",
"list_color": "<string>",
"status": "started",
"archived": {
"user_id": "uDsu0j19",
"time_archived": 1608742037016
}
}
],
"child_card_order": {},
"linked_cards": [
{
"title": "Create illustration for upcoming holidays",
"card_id": "42",
"user_id": "42",
"project_id": "3",
"board_id": "15",
"board_title": "Ideas",
"list_id": "list 1",
"list_title": "list 1",
"status": "started",
"archived": {
"user_id": "uDsu0j19",
"time_archived": 1608742037016
},
"linked_card_type": "blocks",
"icon": {
"src": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"id": "<string>",
"blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj",
"color": "black",
"emoji": "thumbsup"
}
}
],
"archived": {
"user_id": "uDsu0j19",
"time_archived": 1608742037016
},
"archived_list": false,
"tags": [
{
"id": "u-dsu0j19",
"team_id": "u-dsu0j19",
"project_id": "5",
"name": "todo",
"slug": "todo",
"color": "blue",
"total_cards": 17
}
],
"total_comments": 3,
"total_files": 1,
"is_watching": true,
"external_links": [
{
"github_pull_request": {
"id": 123,
"number": 123,
"state": "<string>",
"title": "<string>",
"body": "<string>",
"html_url": "<string>",
"time_created": 1608742037016,
"time_updated": 1608742037016,
"time_closed": 1608742037016,
"time_merged": 1608742037016,
"head": {
"label": "<string>",
"ref": "<string>"
},
"base": {
"label": "<string>",
"ref": "<string>"
},
"draft": true,
"merged": true
},
"generic": {
"url": "<string>",
"id": "550e8400-e29b-41d4-a716-446655440000",
"display_text": "<string>",
"time_added": 1608742037016
}
}
],
"hints": [
{
"type": "tag",
"tag": {},
"relation": {
"card": {
"title": "Create illustration for upcoming holidays",
"card_id": "42",
"user_id": "us4Fsfed",
"project_id": "3",
"board_id": "15",
"board_title": "Ideas",
"list_id": "55",
"list_title": "Done",
"list_color": "<string>",
"status": "started"
},
"similarity": 0.8
}
}
],
"cover_image": {
"src": "data:image/png;base64, iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
"id": "<string>",
"blurhash": "LEHV6nWB2yk8pyoJadR*.7kCMdnj",
"color": "black",
"emoji": "thumbsup",
"positionY": 123
}
}
}{
"error": {
"id": "err5f744ab",
"code": 403,
"sec": "SEC:000-00014",
"message": "You do not have access to this resource",
"date": 1608742037016
}
}