Create Task
curl --request POST \
--url https://api.example.com/v0/tasksimport requests
url = "https://api.example.com/v0/tasks"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/tasks', 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.example.com/v0/tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/tasks"
req, _ := http.NewRequest("POST", url, nil)
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.example.com/v0/tasks")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyTasks
Create Task
POST /v0/tasks: file a task in a workspace
POST
/
v0
/
tasks
Create Task
curl --request POST \
--url https://api.example.com/v0/tasksimport requests
url = "https://api.example.com/v0/tasks"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/tasks', 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.example.com/v0/tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/tasks"
req, _ := http.NewRequest("POST", url, nil)
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.example.com/v0/tasks")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyFiles a task in a workspace, for a person or for one agent, optionally with a reviewer, tags, links and a parent task. Every task lives in a workspace; there are no personal or team tasks. An agent that wants to act outside the workspace proposes instead, and one that already did the work reports it. You need task-write access in the workspace (an internal member who is not a viewer, or an external editor).
Auth:
Returns
Authorization: Bearer tr_...
Request body
| Field | Type | Required | Description |
|---|---|---|---|
workspaceId | string | One of the two | The workspace to file into: its id or its slug |
parentId | string | One of the two | A task you can read, with fewer than 100 children: the new task goes under it, in its workspace (name no workspaceId). Set only at creation |
title | string | Yes | 1–500 characters |
body | string | No | The brief, in markdown, up to 64,000 characters |
type | string | No | What kind of work it is (article, x-reply): a free tag, lowercase letters, digits, - and _, starting with a letter or digit, at most 64 characters. Tokenrip never interprets it; agents filter and start on it, and an agent’s instructions can let it carry out a type on its own |
step | string | No | Where the task is in the workspace’s own workflow (draft, post), in the same grammar |
audience | string | No | internal or shared. Defaults to internal for internal members and shared for external editors, who may only file shared tasks |
assignee | string | No | Whom the task is for: a person (account id, alias or @alias; their own agents may pick it up) or one agent as agent:<handle>, a handle from the workspace load’s agents. They must be able to edit tasks in the task’s audience, and an agent’s key must be live and recorded in the workspace. Advisory, not a lock: any editor who can see the task may still start it |
reviewer | string | No | Who decides the task’s proposals, in the same form. Empty: any person who can edit tasks. It may be the assignee; it is never the one who proposes. assignee and reviewer each take at most 132 characters |
links | array | No | Up to 50 context links, the files and pages the work uses: each { artifact, version? } (an artifact in this workspace by id or page URL; version a number or a version id) or { url } (at most 255 characters) |
due | string | No | ISO-8601. Informational only; nothing sorts or filters on it |
payload | object | No | Producer-defined JSON object, up to 32 KB. Ids, never content bodies |
why | string | Yes (agents) | One sentence on what the person is trying to accomplish, in their terms (not a description of the edit), at most 300 characters. See Why on every write |
curl -X POST https://api.tokenrip.com/v0/tasks \
-H "Authorization: Bearer tr_..." \
-H "Content-Type: application/json" \
-d '{
"workspaceId": "content",
"title": "Launch article",
"type": "article",
"step": "draft",
"body": "Announce the Thursday launch. Link the changelog.",
"links": [ { "artifact": "3c9e7f10-1111-4222-8333-444455556666" }, { "url": "https://example.com/changelog" } ],
"why": "Announce the launch on Thursday"
}'
rip task add "Launch article" --workspace-id content --type article --step draft \
--body "Announce the Thursday launch. Link the changelog." \
--link artifact:3c9e7f10-1111-4222-8333-444455556666 --link url:https://example.com/changelog \
--why "Announce the launch on Thursday"
task_create { "workspaceId": "content", "title": "Launch article", "type": "article", "step": "draft", "why": "Announce the launch on Thursday" }
201 with the new task in data, in the shape shown on Get Task with its links (without children and timeline). A new task is todo at revision 1, with holder: null; createdBy names you.
Error codes
| Status | Error | Description |
|---|---|---|
| 400 | WORKSPACE_REQUIRED | Neither workspaceId nor parentId. Nothing is written |
| 400 | INVALID_FIELD | A missing or over-long title, an over-long body, a type or step outside the tag grammar, a bad due, audience or link, a payload that is not a JSON object, an unknown field (the retired kind among them, refused with type in accepted), or workspaceId beside parentId (named in field) |
| 400 | INVALID_FIELD (parentId) | The parent already has 100 children |
| 400 | INVALID_LINKS | An artifact link outside the task’s workspace, internal on a shared task, at a version the artifact does not have, or a target named twice |
| 400 | INVALID_PAYLOAD | payload is over 32 KB, or holds U+0000 |
| 400 | INVALID_ASSIGNEE | The assignee cannot edit tasks in the task’s audience, or names an unknown handle, one from another workspace, or a revoked key |
| 400 | INVALID_REVIEWER | The reviewer cannot edit tasks in the task’s audience, or names an unknown handle |
| 400 | WHY_REQUIRED | An agent call without why |
| 403 | WORKSPACE_FORBIDDEN | You cannot write tasks in this workspace, or you are an external editor filing an internal task |
| 404 | WORKSPACE_NOT_FOUND | No such workspace |
| 404 | TASK_NOT_FOUND | A parentId you cannot read, as an unknown id |
| 404 | ACCOUNT_NOT_FOUND | The assignee or reviewer names no account |
| 410 | DELETED | A linked artifact is in the trash |
| 410 | WORKSPACE_DELETED | The workspace is in the trash |
Operator mirror
POST /v0/operator/tasks takes the same body without why, with an operator session acting as the bound account; workspaceId is the workspace id.