curl --request POST \ --url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "background": "You ordered a jacket last week. It arrived in the wrong size.", "instructions": "Find the refund policy and start a return.", "name": "Return a delivered order", "steps": [ { "name": "Open order history" }, { "name": "Start a return on the jacket" } ]}'
import requests
url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks"
payload = {
"background": "You ordered a jacket last week. It arrived in the wrong size.",
"instructions": "Find the refund policy and start a return.",
"name": "Return a delivered order",
"steps": [{ "name": "Open order history" }, { "name": "Start a return on the jacket" }]
}
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({
background: 'You ordered a jacket last week. It arrived in the wrong size.',
instructions: 'Find the refund policy and start a return.',
name: 'Return a delivered order',
steps: [{name: 'Open order history'}, {name: 'Start a return on the jacket'}]
})
};
fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/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.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks",
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([
'background' => 'You ordered a jacket last week. It arrived in the wrong size.',
'instructions' => 'Find the refund policy and start a return.',
'name' => 'Return a delivered order',
'steps' => [
[
'name' => 'Open order history'
],
[
'name' => 'Start a return on the jacket'
]
]
]),
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.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks"
payload := strings.NewReader("{\n \"background\": \"You ordered a jacket last week. It arrived in the wrong size.\",\n \"instructions\": \"Find the refund policy and start a return.\",\n \"name\": \"Return a delivered order\",\n \"steps\": [\n {\n \"name\": \"Open order history\"\n },\n {\n \"name\": \"Start a return on the jacket\"\n }\n ]\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.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"background\": \"You ordered a jacket last week. It arrived in the wrong size.\",\n \"instructions\": \"Find the refund policy and start a return.\",\n \"name\": \"Return a delivered order\",\n \"steps\": [\n {\n \"name\": \"Open order history\"\n },\n {\n \"name\": \"Start a return on the jacket\"\n }\n ]\n}")
.asString();
require 'uri'
require 'net/http'
url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks")
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 \"background\": \"You ordered a jacket last week. It arrived in the wrong size.\",\n \"instructions\": \"Find the refund policy and start a return.\",\n \"name\": \"Return a delivered order\",\n \"steps\": [\n {\n \"name\": \"Open order history\"\n },\n {\n \"name\": \"Start a return on the jacket\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
Register a task: a named intent a session can bind by id.
Registering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session.
Send an Idempotency-Key header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409.
get_or_create is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer Idempotency-Key for retries and PATCH to reconcile content.
POST
/
api
/
v1
/
workspaces
/
{workspace_id}
/
tasks
Create Task
curl --request POST \ --url https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "background": "You ordered a jacket last week. It arrived in the wrong size.", "instructions": "Find the refund policy and start a return.", "name": "Return a delivered order", "steps": [ { "name": "Open order history" }, { "name": "Start a return on the jacket" } ]}'
import requests
url = "https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks"
payload = {
"background": "You ordered a jacket last week. It arrived in the wrong size.",
"instructions": "Find the refund policy and start a return.",
"name": "Return a delivered order",
"steps": [{ "name": "Open order history" }, { "name": "Start a return on the jacket" }]
}
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({
background: 'You ordered a jacket last week. It arrived in the wrong size.',
instructions: 'Find the refund policy and start a return.',
name: 'Return a delivered order',
steps: [{name: 'Open order history'}, {name: 'Start a return on the jacket'}]
})
};
fetch('https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/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.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks",
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([
'background' => 'You ordered a jacket last week. It arrived in the wrong size.',
'instructions' => 'Find the refund policy and start a return.',
'name' => 'Return a delivered order',
'steps' => [
[
'name' => 'Open order history'
],
[
'name' => 'Start a return on the jacket'
]
]
]),
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.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks"
payload := strings.NewReader("{\n \"background\": \"You ordered a jacket last week. It arrived in the wrong size.\",\n \"instructions\": \"Find the refund policy and start a return.\",\n \"name\": \"Return a delivered order\",\n \"steps\": [\n {\n \"name\": \"Open order history\"\n },\n {\n \"name\": \"Start a return on the jacket\"\n }\n ]\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.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"background\": \"You ordered a jacket last week. It arrived in the wrong size.\",\n \"instructions\": \"Find the refund policy and start a return.\",\n \"name\": \"Return a delivered order\",\n \"steps\": [\n {\n \"name\": \"Open order history\"\n },\n {\n \"name\": \"Start a return on the jacket\"\n }\n ]\n}")
.asString();
require 'uri'
require 'net/http'
url = URI("https://api.ishlabs.io/api/v1/workspaces/{workspace_id}/tasks")
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 \"background\": \"You ordered a jacket last week. It arrived in the wrong size.\",\n \"instructions\": \"Find the refund policy and start a return.\",\n \"name\": \"Return a delivered order\",\n \"steps\": [\n {\n \"name\": \"Open order history\"\n },\n {\n \"name\": \"Start a return on the jacket\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
Workspace API key as a bearer token: Authorization: Bearer ish_sk_live_.... Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: sessions:run (create a session, submit turns, close), sessions:read (read the session and its decision trace), environments:read and environments:write (manage the workspace's registered environments), tasks:read and tasks:write (manage the workspace's registered tasks), people:read and people:write (the people the workspace can run a session for), and usage:read (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with sessions:run, sessions:read, and tasks:read by default; every other scope must be requested, people:read and usage:read included. An ish user access token also works on the same header for personal scripts.
What the person is trying to do, in their own terms. Rendered into their prompt as the situation paragraph, exactly as a session's inline instructions are.
Background the person is treated as already knowing. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.
Idempotent register for CI: when a live task with this name (case-insensitive, per workspace) already exists, return it with 200 instead of 409. The existing task is returned as is: nothing on this request is applied to it.
The atomic actions a run should be checked against afterwards. Never shown to the person doing the run. Step ids are permanent identity: an id you supply is kept verbatim, a missing one is minted server-side. Accepted and stored; not yet consumed by API sessions.
Maximum array length: 50
Show child attributes
Response
The existing task, RETURNED AS IS: nothing on this request was applied to it. Two paths reach here: an Idempotency-Key replay (same key, same body), or get_or_create with a live task already holding this name.
Set when the task is archived (DELETE). An archived task stays readable by id so existing sessions keep resolving, is hidden from the default list, refuses new sessions (409), and frees its name for reuse.
Background the person is treated as already knowing, or null. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.
The actions a run is checked against afterwards, or null when the task has none. Steps are never shown to the person doing the run. Accepted and stored; not yet consumed by API sessions.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"ish","description":"Documentation for the ish CLI and MCP server. Simulate a visit and read the reactions before you ship.","colors":{"primary":"#C8623F","light":"#D87A55","dark":"#262220"},"logo":{"light":"https://mintcdn.com/ish/4MaJn6-B7_NnPAml/logo/light.svg?fit=max\u0026auto=format\u0026n=4MaJn6-B7_NnPAml\u0026q=85\u0026s=f0edab6b74c19bec95794ee94d7270c2","dark":"https://mintcdn.com/ish/4MaJn6-B7_NnPAml/logo/dark.svg?fit=max\u0026auto=format\u0026n=4MaJn6-B7_NnPAml\u0026q=85\u0026s=da9e886222890dc4edeaf5b77b455102"},"favicon":{"light":"https://mintcdn.com/ish/4MaJn6-B7_NnPAml/favicon.svg?fit=max\u0026auto=format\u0026n=4MaJn6-B7_NnPAml\u0026q=85\u0026s=871b7f0a040fb0e8c3293911bcbfd37d","dark":"https://mintcdn.com/ish/4MaJn6-B7_NnPAml/favicon-dark.svg?fit=max\u0026auto=format\u0026n=4MaJn6-B7_NnPAml\u0026q=85\u0026s=8915499d3e98ef136443c3c38b96e4b9"},"appearance":{"default":"system"},"background":{"color":{"light":"#FDFCFB","dark":"#1A1816"}},"navbar":{"links":[{"href":"https://app.ishlabs.io","label":"Sign in"}],"primary":{"type":"button","label":"Get ish free","href":"https://app.ishlabs.io"}},"footer":{"socials":{"github":"https://github.com/ishlabs"},"links":[{"header":"Product","items":[{"label":"ishlabs.io","href":"https://ishlabs.io"},{"label":"Pricing","href":"https://ishlabs.io/pricing"},{"label":"Sign in","href":"https://app.ishlabs.io"}]}]},"fonts":{"heading":{"family":"Inter"},"body":{"family":"Inter"}},"contextual":{"options":["copy","view","chatgpt","claude","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"global":{"anchors":[{"anchor":"GitHub","icon":"github","href":"https://github.com/ishlabs"},{"anchor":"ishlabs.io","icon":"globe","href":"https://ishlabs.io"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"ish","hasAudioNarration":false,"actualSubdomain":"ish","customDomains":["docs.ishlabs.io"],"gitSource":{"type":"github","owner":"ishlabs","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"feedback":{"thumbs":false},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6af0209f0311aab340dbb5c0","clientVersion":"0.0.4094","searchFilterCounts":[{"language":"default","tag":"Guides","count":45},{"language":"default","tag":"API","count":42},{"language":"default","tag":"API reference","count":28},{"language":"default","tag":"CLI Reference","count":28},{"language":"default","tag":"Core concepts","count":26},{"language":"default","tag":"MCP Reference","count":21},{"language":"default","tag":"Commands","count":20},{"language":"default","tag":"Overview","count":15},{"language":"default","tag":"Tools","count":13},{"language":"default","tag":"How-to guides","count":9}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"comment-mode","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"[data-component-part=\"card-icon\"] svg{background-color:#262220!important}html.dark [data-component-part=\"card-icon\"] svg{background-color:#e8e3de!important}html.dark img[src*=\"/logos/\"]{filter:invert(0.91) brightness(1.03)}#content-area a[href]>div:hover,.ish-card:hover{border-color:#d87a55;transition:border-color 0.15s ease, box-shadow 0.15s ease}"}],"page":{"pagePath":"api/reference/tasks/create-task","slug":"/api/reference/tasks/create-task","pageMetadata":{"title":"Create Task","description":"Register a task: a named intent a session can bind by id.\n\nRegistering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session.\n\nSend an `Idempotency-Key` header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409.\n\n`get_or_create` is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer `Idempotency-Key` for retries and PATCH to reconcile content.","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/workspaces/{workspace_id}/tasks","href":"/api/reference/tasks/create-task","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Register a task: a named intent a session can bind by id.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Registering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Send an \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"get_or_create\"\n }), \" is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" for retries and PATCH to reconcile content.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Create Task","description":"Register a task: a named intent a session can bind by id.\n\nRegistering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session.\n\nSend an `Idempotency-Key` header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409.\n\n`get_or_create` is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer `Idempotency-Key` for retries and PATCH to reconcile content.","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/workspaces/{workspace_id}/tasks","href":"/api/reference/tasks/create-task","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"description":"Register a task: a named intent a session can bind by id.\n\nRegistering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session.\n\nSend an `Idempotency-Key` header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409.\n\n`get_or_create` is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer `Idempotency-Key` for retries and PATCH to reconcile content.","operationId":"createTask","parameters":["48f70ceb-12db-4db9-bb5b-0d4df2fb82e0","2da49e5d-dca6-408d-a02d-2a6638d5acf9"],"requestBody":"8ec3cc60-7275-4bd3-95ba-bca969ef4479","responses":{"200":"239b55c7-355f-4f93-af53-eee579e9e78d","201":"d1b6ce9f-fb2f-447b-9ef9-e434a1ec60b4","401":"f818c65a-70e9-43a0-bd59-64f9f8a5c286","403":"ab5ccd31-66e2-4fd5-8783-78469aa7bf6a","404":"41d1aaa2-5ef8-4152-a00f-7040939c08c5","409":"294a8701-9cbe-46dd-9541-2aa64a031b36","422":"623fbb8a-fd10-4f79-ad1e-e9edf167398c","429":"0f7726a3-cda9-464d-9aa2-2dafa4081242"},"security":["51753f64-6d01-460b-88c8-b6c4af155f1f"],"summary":"Create Task","tags":["tasks"],"method":"post","type":"path","servers":["22c3a961-b6d9-4922-b5aa-d0aac292aa39"],"path":"/api/v1/workspaces/{workspace_id}/tasks","baseUrlOptions":["https://api.ishlabs.io"],"title":"Create Task","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"48f70ceb-12db-4db9-bb5b-0d4df2fb82e0":{"in":"path","name":"workspace_id","required":true,"schema":{"format":"uuid","title":"Workspace Id","type":"string","isRequired":true,"uniqueKey":"","typeLabel":"string\u003cuuid>"}},"2da49e5d-dca6-408d-a02d-2a6638d5acf9":{"in":"header","name":"Idempotency-Key","required":false,"schema":{"oneOf":[{"type":"string","title":"Idempotency-Key","uniqueKey":"oneOf.0","typeLabel":"string"},{"type":"null","title":"Idempotency-Key","uniqueKey":"oneOf.1","typeLabel":"null"}],"isRequired":false,"uniqueKey":"","typeLabel":"string | null"}}},"requestBody":{"content":{"application/json":{"examples":{"default":{"title":"default","value":{"background":"You ordered a jacket last week. It arrived in the wrong size.","instructions":"Find the refund policy and start a return.","name":"Return a delivered order","steps":[{"name":"Open order history"},{"name":"Start a return on the jacket"}]}}},"schema":{"additionalProperties":false,"properties":{"instructions":{"description":"What the person is trying to do, in their own terms. Rendered into their prompt as the situation paragraph, exactly as a session's inline instructions are.","maxLength":2000,"minLength":1,"title":"Instructions","type":"string","isRequired":true,"uniqueKey":"instructions","typeLabel":"string"},"name":{"maxLength":120,"minLength":1,"title":"Name","type":"string","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"background":{"oneOf":[{"type":"string","title":"Background","description":"Background the person is treated as already knowing. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.","maxLength":8000,"uniqueKey":"background.oneOf.0","typeLabel":"string"},{"type":"null","title":"Background","description":"Background the person is treated as already knowing. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.","uniqueKey":"background.oneOf.1","typeLabel":"null"}],"uniqueKey":"background","typeLabel":"string | null"},"get_or_create":{"default":false,"description":"Idempotent register for CI: when a live task with this name (case-insensitive, per workspace) already exists, return it with 200 instead of 409. The existing task is returned as is: nothing on this request is applied to it.","title":"Get Or Create","type":"boolean","uniqueKey":"get_or_create","typeLabel":"boolean"},"steps":{"oneOf":[{"type":"array","items":{"description":"One atomic action, for verifying after the session what the person actually accomplished.\n\n`name` is required (a short verb phrase); `description` is optional nuance. `id` is the step's permanent identity: send back an id you already hold and it is kept verbatim, or omit it and one is derived from the name. Responses always carry it.","properties":{"name":{"maxLength":80,"minLength":1,"title":"Name","type":"string","isRequired":true,"uniqueKey":"steps.oneOf.0.items.[INDEX].name","typeLabel":"string"},"description":{"oneOf":[{"type":"string","title":"Description","maxLength":500,"uniqueKey":"steps.oneOf.0.items.[INDEX].description.oneOf.0","typeLabel":"string"},{"type":"null","title":"Description","uniqueKey":"steps.oneOf.0.items.[INDEX].description.oneOf.1","typeLabel":"null"}],"uniqueKey":"steps.oneOf.0.items.[INDEX].description","typeLabel":"string | null"},"id":{"oneOf":[{"type":"string","title":"Id","maxLength":64,"uniqueKey":"steps.oneOf.0.items.[INDEX].id.oneOf.0","typeLabel":"string"},{"type":"null","title":"Id","uniqueKey":"steps.oneOf.0.items.[INDEX].id.oneOf.1","typeLabel":"null"}],"uniqueKey":"steps.oneOf.0.items.[INDEX].id","typeLabel":"string | null"}},"required":["name"],"title":"TaskStep","type":"object","uniqueKey":"steps.oneOf.0.items.[INDEX]","typeLabel":"TaskStep · object"},"title":"Steps","description":"The atomic actions a run should be checked against afterwards. Never shown to the person doing the run. Step ids are permanent identity: an id you supply is kept verbatim, a missing one is minted server-side. Accepted and stored; not yet consumed by API sessions.","maxItems":50,"uniqueKey":"steps.oneOf.0","typeLabel":"TaskStep · object[]"},{"type":"null","title":"Steps","description":"The atomic actions a run should be checked against afterwards. Never shown to the person doing the run. Step ids are permanent identity: an id you supply is kept verbatim, a missing one is minted server-side. Accepted and stored; not yet consumed by API sessions.","uniqueKey":"steps.oneOf.1","typeLabel":"null"}],"uniqueKey":"steps","typeLabel":"TaskStep · object[] | null"}},"required":["name","instructions"],"title":"CreateTaskRequest","type":"object","uniqueKey":"","typeLabel":"CreateTaskRequest · object"},"exampleType":"examples"}},"required":true,"exampleType":"examples"},"responses":{"239b55c7-355f-4f93-af53-eee579e9e78d":{"content":{"application/json":{"schema":{"description":"A registered task as the caller sees it.","properties":{"archived_at":{"oneOf":[{"type":"string","title":"Archived At","description":"Set when the task is archived (DELETE). An archived task stays readable by id so existing sessions keep resolving, is hidden from the default list, refuses new sessions (409), and frees its name for reuse.","format":"date-time","isRequired":true,"uniqueKey":"archived_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","title":"Archived At","description":"Set when the task is archived (DELETE). An archived task stays readable by id so existing sessions keep resolving, is hidden from the default list, refuses new sessions (409), and frees its name for reuse.","isRequired":true,"uniqueKey":"archived_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"archived_at","typeLabel":"string\u003cdate-time> | null"},"background":{"oneOf":[{"type":"string","title":"Background","description":"Background the person is treated as already knowing, or null. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.","isRequired":true,"uniqueKey":"background.oneOf.0","typeLabel":"string"},{"type":"null","title":"Background","description":"Background the person is treated as already knowing, or null. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.","isRequired":true,"uniqueKey":"background.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"background","typeLabel":"string | null"},"created_at":{"format":"date-time","title":"Created At","type":"string","isRequired":true,"uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"id":{"format":"uuid","title":"Id","type":"string","isRequired":true,"uniqueKey":"id","typeLabel":"string\u003cuuid>"},"instructions":{"title":"Instructions","type":"string","isRequired":true,"uniqueKey":"instructions","typeLabel":"string"},"name":{"title":"Name","type":"string","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"revision":{"description":"Increments on every write to this task. Sessions freeze the revision they bound, so runs are comparable within a revision of the content.","title":"Revision","type":"integer","isRequired":true,"uniqueKey":"revision","typeLabel":"integer"},"steps":{"oneOf":[{"type":"array","items":{"description":"A stored step as the caller sees it (id always present).","properties":{"id":{"title":"Id","type":"string","isRequired":true,"uniqueKey":"steps.oneOf.0.items.[INDEX].id","typeLabel":"string"},"name":{"title":"Name","type":"string","isRequired":true,"uniqueKey":"steps.oneOf.0.items.[INDEX].name","typeLabel":"string"},"description":{"oneOf":[{"type":"string","title":"Description","uniqueKey":"steps.oneOf.0.items.[INDEX].description.oneOf.0","typeLabel":"string"},{"type":"null","title":"Description","uniqueKey":"steps.oneOf.0.items.[INDEX].description.oneOf.1","typeLabel":"null"}],"uniqueKey":"steps.oneOf.0.items.[INDEX].description","typeLabel":"string | null"}},"required":["id","name"],"title":"TaskStepView","type":"object","uniqueKey":"steps.oneOf.0.items.[INDEX]","typeLabel":"TaskStepView · object"},"title":"Steps","description":"The actions a run is checked against afterwards, or null when the task has none. Steps are never shown to the person doing the run. Accepted and stored; not yet consumed by API sessions.","isRequired":true,"uniqueKey":"steps.oneOf.0","typeLabel":"TaskStepView · object[]"},{"type":"null","title":"Steps","description":"The actions a run is checked against afterwards, or null when the task has none. Steps are never shown to the person doing the run. Accepted and stored; not yet consumed by API sessions.","isRequired":true,"uniqueKey":"steps.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"steps","typeLabel":"TaskStepView · object[] | null"},"updated_at":{"format":"date-time","title":"Updated At","type":"string","isRequired":true,"uniqueKey":"updated_at","typeLabel":"string\u003cdate-time>"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string","isRequired":true,"uniqueKey":"workspace_id","typeLabel":"string\u003cuuid>"}},"required":["id","workspace_id","name","instructions","background","steps","revision","archived_at","created_at","updated_at"],"title":"TaskResponse","type":"object","uniqueKey":"","typeLabel":"TaskResponse · object"},"examples":{"Example":{"title":"Example","value":{"archived_at":"2023-11-07T05:31:56Z","background":"\u003cstring>","created_at":"2023-11-07T05:31:56Z","id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","instructions":"\u003cstring>","name":"\u003cstring>","revision":123,"steps":[{"id":"\u003cstring>","name":"\u003cstring>","description":"\u003cstring>"}],"updated_at":"2023-11-07T05:31:56Z","workspace_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a"}}},"exampleType":"generated"}},"description":"The existing task, RETURNED AS IS: nothing on this request was applied to it. Two paths reach here: an `Idempotency-Key` replay (same key, same body), or `get_or_create` with a live task already holding this name.","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"},"d1b6ce9f-fb2f-447b-9ef9-e434a1ec60b4":{"content":{"application/json":{"schema":{"description":"A registered task as the caller sees it.","properties":{"archived_at":{"oneOf":[{"type":"string","title":"Archived At","description":"Set when the task is archived (DELETE). An archived task stays readable by id so existing sessions keep resolving, is hidden from the default list, refuses new sessions (409), and frees its name for reuse.","format":"date-time","isRequired":true,"uniqueKey":"archived_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","title":"Archived At","description":"Set when the task is archived (DELETE). An archived task stays readable by id so existing sessions keep resolving, is hidden from the default list, refuses new sessions (409), and frees its name for reuse.","isRequired":true,"uniqueKey":"archived_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"archived_at","typeLabel":"string\u003cdate-time> | null"},"background":{"oneOf":[{"type":"string","title":"Background","description":"Background the person is treated as already knowing, or null. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.","isRequired":true,"uniqueKey":"background.oneOf.0","typeLabel":"string"},{"type":"null","title":"Background","description":"Background the person is treated as already knowing, or null. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.","isRequired":true,"uniqueKey":"background.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"background","typeLabel":"string | null"},"created_at":{"format":"date-time","title":"Created At","type":"string","isRequired":true,"uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"id":{"format":"uuid","title":"Id","type":"string","isRequired":true,"uniqueKey":"id","typeLabel":"string\u003cuuid>"},"instructions":{"title":"Instructions","type":"string","isRequired":true,"uniqueKey":"instructions","typeLabel":"string"},"name":{"title":"Name","type":"string","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"revision":{"description":"Increments on every write to this task. Sessions freeze the revision they bound, so runs are comparable within a revision of the content.","title":"Revision","type":"integer","isRequired":true,"uniqueKey":"revision","typeLabel":"integer"},"steps":{"oneOf":[{"type":"array","items":{"description":"A stored step as the caller sees it (id always present).","properties":{"id":{"title":"Id","type":"string","isRequired":true,"uniqueKey":"steps.oneOf.0.items.[INDEX].id","typeLabel":"string"},"name":{"title":"Name","type":"string","isRequired":true,"uniqueKey":"steps.oneOf.0.items.[INDEX].name","typeLabel":"string"},"description":{"oneOf":[{"type":"string","title":"Description","uniqueKey":"steps.oneOf.0.items.[INDEX].description.oneOf.0","typeLabel":"string"},{"type":"null","title":"Description","uniqueKey":"steps.oneOf.0.items.[INDEX].description.oneOf.1","typeLabel":"null"}],"uniqueKey":"steps.oneOf.0.items.[INDEX].description","typeLabel":"string | null"}},"required":["id","name"],"title":"TaskStepView","type":"object","uniqueKey":"steps.oneOf.0.items.[INDEX]","typeLabel":"TaskStepView · object"},"title":"Steps","description":"The actions a run is checked against afterwards, or null when the task has none. Steps are never shown to the person doing the run. Accepted and stored; not yet consumed by API sessions.","isRequired":true,"uniqueKey":"steps.oneOf.0","typeLabel":"TaskStepView · object[]"},{"type":"null","title":"Steps","description":"The actions a run is checked against afterwards, or null when the task has none. Steps are never shown to the person doing the run. Accepted and stored; not yet consumed by API sessions.","isRequired":true,"uniqueKey":"steps.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"steps","typeLabel":"TaskStepView · object[] | null"},"updated_at":{"format":"date-time","title":"Updated At","type":"string","isRequired":true,"uniqueKey":"updated_at","typeLabel":"string\u003cdate-time>"},"workspace_id":{"format":"uuid","title":"Workspace Id","type":"string","isRequired":true,"uniqueKey":"workspace_id","typeLabel":"string\u003cuuid>"}},"required":["id","workspace_id","name","instructions","background","steps","revision","archived_at","created_at","updated_at"],"title":"TaskResponse","type":"object","uniqueKey":"","typeLabel":"TaskResponse · object"},"examples":{"Example":{"title":"Example","value":{"archived_at":"2023-11-07T05:31:56Z","background":"\u003cstring>","created_at":"2023-11-07T05:31:56Z","id":"3c90c3cc-0d44-4b50-8888-8dd25736052a","instructions":"\u003cstring>","name":"\u003cstring>","revision":123,"steps":[{"id":"\u003cstring>","name":"\u003cstring>","description":"\u003cstring>"}],"updated_at":"2023-11-07T05:31:56Z","workspace_id":"3c90c3cc-0d44-4b50-8888-8dd25736052a"}}},"exampleType":"generated"}},"description":"Successful Response","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"},"f818c65a-70e9-43a0-bd59-64f9f8a5c286":{"content":{"application/json":{"schema":{"description":"Generic error envelope for 4xx/5xx responses other than request-shape validation.","properties":{"detail":{"oneOf":[{"type":"string","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","isRequired":true,"uniqueKey":"detail.oneOf.0","typeLabel":"string"},{"type":"object","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","additionalProperties":true,"isRequired":true,"uniqueKey":"detail.oneOf.1","typeLabel":"Detail · object"}],"isRequired":true,"uniqueKey":"detail","typeLabel":"string | Detail · object"},"request_id":{"description":"Correlation id; identical to the `X-Request-Id` response header. Quote it in support requests.","title":"Request Id","type":"string","isRequired":true,"uniqueKey":"request_id","typeLabel":"string"},"docs_url":{"description":"Link to this error's entry in the error catalog. Present whenever `detail` carries a registered `error_kind`; absent on unclassified errors.","title":"Docs Url","type":"string","uniqueKey":"docs_url","typeLabel":"string"}},"required":["detail","request_id"],"title":"Error","type":"object","uniqueKey":"","typeLabel":"Error · object"},"examples":{"Example":{"title":"Example","value":{"detail":"\u003cstring>","request_id":"\u003cstring>","docs_url":"\u003cstring>"}}},"exampleType":"generated"}},"description":"The bearer token is missing, malformed, unknown, or revoked (`detail.error_kind = 'invalid_api_key'`). One kind covers all four deliberately: distinguishing them would confirm which guesses are real keys.","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"},"ab5ccd31-66e2-4fd5-8783-78469aa7bf6a":{"content":{"application/json":{"schema":{"description":"Generic error envelope for 4xx/5xx responses other than request-shape validation.","properties":{"detail":{"oneOf":[{"type":"string","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","isRequired":true,"uniqueKey":"detail.oneOf.0","typeLabel":"string"},{"type":"object","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","additionalProperties":true,"isRequired":true,"uniqueKey":"detail.oneOf.1","typeLabel":"Detail · object"}],"isRequired":true,"uniqueKey":"detail","typeLabel":"string | Detail · object"},"request_id":{"description":"Correlation id; identical to the `X-Request-Id` response header. Quote it in support requests.","title":"Request Id","type":"string","isRequired":true,"uniqueKey":"request_id","typeLabel":"string"},"docs_url":{"description":"Link to this error's entry in the error catalog. Present whenever `detail` carries a registered `error_kind`; absent on unclassified errors.","title":"Docs Url","type":"string","uniqueKey":"docs_url","typeLabel":"string"}},"required":["detail","request_id"],"title":"Error","type":"object","uniqueKey":"","typeLabel":"Error · object"},"examples":{"Example":{"title":"Example","value":{"detail":"\u003cstring>","request_id":"\u003cstring>","docs_url":"\u003cstring>"}}},"exampleType":"generated"}},"description":"The API key lacks the `tasks:write` scope (`detail.error_kind = 'insufficient_scope'`, with `detail.required_scope = 'tasks:write'`). Mint a key that includes it; an ish user access token is unconstrained by scopes.","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"},"41d1aaa2-5ef8-4152-a00f-7040939c08c5":{"content":{"application/json":{"schema":{"description":"Generic error envelope for 4xx/5xx responses other than request-shape validation.","properties":{"detail":{"oneOf":[{"type":"string","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","isRequired":true,"uniqueKey":"detail.oneOf.0","typeLabel":"string"},{"type":"object","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","additionalProperties":true,"isRequired":true,"uniqueKey":"detail.oneOf.1","typeLabel":"Detail · object"}],"isRequired":true,"uniqueKey":"detail","typeLabel":"string | Detail · object"},"request_id":{"description":"Correlation id; identical to the `X-Request-Id` response header. Quote it in support requests.","title":"Request Id","type":"string","isRequired":true,"uniqueKey":"request_id","typeLabel":"string"},"docs_url":{"description":"Link to this error's entry in the error catalog. Present whenever `detail` carries a registered `error_kind`; absent on unclassified errors.","title":"Docs Url","type":"string","uniqueKey":"docs_url","typeLabel":"string"}},"required":["detail","request_id"],"title":"Error","type":"object","uniqueKey":"","typeLabel":"Error · object"},"examples":{"Example":{"title":"Example","value":{"detail":"\u003cstring>","request_id":"\u003cstring>","docs_url":"\u003cstring>"}}},"exampleType":"generated"}},"description":"The workspace (`workspace_id`) was not found, or is not reachable with this credential. `detail.error_kind` is `workspace_not_found`.","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"},"294a8701-9cbe-46dd-9541-2aa64a031b36":{"content":{"application/json":{"schema":{"description":"Generic error envelope for 4xx/5xx responses other than request-shape validation.","properties":{"detail":{"oneOf":[{"type":"string","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","isRequired":true,"uniqueKey":"detail.oneOf.0","typeLabel":"string"},{"type":"object","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","additionalProperties":true,"isRequired":true,"uniqueKey":"detail.oneOf.1","typeLabel":"Detail · object"}],"isRequired":true,"uniqueKey":"detail","typeLabel":"string | Detail · object"},"request_id":{"description":"Correlation id; identical to the `X-Request-Id` response header. Quote it in support requests.","title":"Request Id","type":"string","isRequired":true,"uniqueKey":"request_id","typeLabel":"string"},"docs_url":{"description":"Link to this error's entry in the error catalog. Present whenever `detail` carries a registered `error_kind`; absent on unclassified errors.","title":"Docs Url","type":"string","uniqueKey":"docs_url","typeLabel":"string"}},"required":["detail","request_id"],"title":"Error","type":"object","uniqueKey":"","typeLabel":"Error · object"},"examples":{"Example":{"title":"Example","value":{"detail":"\u003cstring>","request_id":"\u003cstring>","docs_url":"\u003cstring>"}}},"exampleType":"generated"}},"description":"`detail.error_kind` is `task_name_taken` (a task with this name already exists in the workspace; names are unique per workspace, case-insensitive) or `idempotency_conflict` (the `Idempotency-Key` was reused with a different request body).","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"},"623fbb8a-fd10-4f79-ad1e-e9edf167398c":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"ValidationError","description":"Request body / parameter validation failure (HTTP 422). A field-level envelope so callers can pinpoint the offending field, value, and allowed values without parsing prose.","required":["error","error_code","status","retryable","detail","errors"],"properties":{"detail":{"title":"Detail","type":"string","isRequired":true,"uniqueKey":"oneOf.0.detail","typeLabel":"string"},"error":{"title":"Error","type":"string","isRequired":true,"uniqueKey":"oneOf.0.error","typeLabel":"string"},"error_code":{"description":"Stable machine code, e.g. `validation_error`.","title":"Error Code","type":"string","isRequired":true,"uniqueKey":"oneOf.0.error_code","typeLabel":"string"},"errors":{"items":{"description":"One field-level entry in a ValidationError envelope.","properties":{"loc":{"description":"Path to the offending field.","items":{"oneOf":[{"type":"string","uniqueKey":"oneOf.0.errors.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"oneOf.0.errors.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"oneOf.0.errors.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"title":"Location","type":"array","isRequired":true,"uniqueKey":"oneOf.0.errors.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"title":"Message","type":"string","isRequired":true,"uniqueKey":"oneOf.0.errors.items.[INDEX].msg","typeLabel":"string"},"type":{"title":"Error Type","type":"string","isRequired":true,"uniqueKey":"oneOf.0.errors.items.[INDEX].type","typeLabel":"string"},"allowed_values":{"description":"For enum/literal failures, the accepted values.","items":{"oneOf":[{}],"uniqueKey":"oneOf.0.errors.items.[INDEX].allowed_values.items.[INDEX]","typeLabel":"any"},"title":"Allowed Values","type":"array","uniqueKey":"oneOf.0.errors.items.[INDEX].allowed_values","typeLabel":"any[]"},"input":{"oneOf":[{"type":"string","title":"Input","description":"Offending value (truncated); omitted for containers.","uniqueKey":"oneOf.0.errors.items.[INDEX].input.oneOf.0","typeLabel":"string"},{"type":"number","title":"Input","description":"Offending value (truncated); omitted for containers.","uniqueKey":"oneOf.0.errors.items.[INDEX].input.oneOf.1","typeLabel":"number"},{"type":"boolean","title":"Input","description":"Offending value (truncated); omitted for containers.","uniqueKey":"oneOf.0.errors.items.[INDEX].input.oneOf.2","typeLabel":"boolean"},{"type":"null","title":"Input","description":"Offending value (truncated); omitted for containers.","uniqueKey":"oneOf.0.errors.items.[INDEX].input.oneOf.3","typeLabel":"null"}],"uniqueKey":"oneOf.0.errors.items.[INDEX].input","typeLabel":"string | number | boolean | null"}},"required":["loc","msg","type"],"title":"FieldError","type":"object","uniqueKey":"oneOf.0.errors.items.[INDEX]","typeLabel":"FieldError · object"},"title":"Errors","type":"array","isRequired":true,"uniqueKey":"oneOf.0.errors","typeLabel":"FieldError · object[]"},"retryable":{"title":"Retryable","type":"boolean","isRequired":true,"uniqueKey":"oneOf.0.retryable","typeLabel":"boolean"},"status":{"title":"Status","type":"integer","isRequired":true,"uniqueKey":"oneOf.0.status","typeLabel":"integer"},"suggestions":{"items":{"type":"string","uniqueKey":"oneOf.0.suggestions.items.[INDEX]","typeLabel":"string"},"title":"Suggestions","type":"array","uniqueKey":"oneOf.0.suggestions","typeLabel":"string[]"}},"uniqueKey":"oneOf.0","typeLabel":"ValidationError · object"},{"type":"object","title":"Error","description":"Generic error envelope for 4xx/5xx responses other than request-shape validation.","required":["detail","request_id"],"properties":{"detail":{"oneOf":[{"type":"string","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","isRequired":true,"uniqueKey":"oneOf.1.detail.oneOf.0","typeLabel":"string"},{"type":"object","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","additionalProperties":true,"isRequired":true,"uniqueKey":"oneOf.1.detail.oneOf.1","typeLabel":"Detail · object"}],"isRequired":true,"uniqueKey":"oneOf.1.detail","typeLabel":"string | Detail · object"},"request_id":{"description":"Correlation id; identical to the `X-Request-Id` response header. Quote it in support requests.","title":"Request Id","type":"string","isRequired":true,"uniqueKey":"oneOf.1.request_id","typeLabel":"string"},"docs_url":{"description":"Link to this error's entry in the error catalog. Present whenever `detail` carries a registered `error_kind`; absent on unclassified errors.","title":"Docs Url","type":"string","uniqueKey":"oneOf.1.docs_url","typeLabel":"string"}},"uniqueKey":"oneOf.1","typeLabel":"Error · object"}],"uniqueKey":"","typeLabel":"ValidationError · object | Error · object"},"examples":{"Example":{"title":"Example","value":{"detail":"\u003cstring>","error":"\u003cstring>","error_code":"\u003cstring>","errors":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>","allowed_values":["\u003cunknown>"],"input":"\u003cstring>"}],"retryable":true,"status":123,"suggestions":["\u003cstring>"]}}},"exampleType":"generated"}},"description":"Validation error. A request-shape failure uses the `ValidationError` envelope; a handler-raised domain-validation refusal uses the `Error` envelope.","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"},"0f7726a3-cda9-464d-9aa2-2dafa4081242":{"content":{"application/json":{"schema":{"description":"Generic error envelope for 4xx/5xx responses other than request-shape validation.","properties":{"detail":{"oneOf":[{"type":"string","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","isRequired":true,"uniqueKey":"detail.oneOf.0","typeLabel":"string"},{"type":"object","title":"Detail","description":"A human-readable message, OR a structured object carrying a machine-readable `error_kind` (e.g. `idempotency_conflict`, `turn_index_mismatch`, `decision_invalid`).","additionalProperties":true,"isRequired":true,"uniqueKey":"detail.oneOf.1","typeLabel":"Detail · object"}],"isRequired":true,"uniqueKey":"detail","typeLabel":"string | Detail · object"},"request_id":{"description":"Correlation id; identical to the `X-Request-Id` response header. Quote it in support requests.","title":"Request Id","type":"string","isRequired":true,"uniqueKey":"request_id","typeLabel":"string"},"docs_url":{"description":"Link to this error's entry in the error catalog. Present whenever `detail` carries a registered `error_kind`; absent on unclassified errors.","title":"Docs Url","type":"string","uniqueKey":"docs_url","typeLabel":"string"}},"required":["detail","request_id"],"title":"Error","type":"object","uniqueKey":"","typeLabel":"Error · object"},"examples":{"Example":{"title":"Example","value":{"detail":"\u003cstring>","request_id":"\u003cstring>","docs_url":"\u003cstring>"}}},"exampleType":"generated"}},"description":"The API key's request rate limit is exceeded (`detail.error_kind = 'rate_limited'`). Transient: retry after the `Retry-After` interval, also echoed as `detail.retry_after_seconds`. Not applied to user access tokens.","headers":{"X-Request-Id":{"description":"Per-response correlation id, present on EVERY response (success and error). Error bodies echo it as `request_id`.","schema":{"type":"string"}},"x-ratelimit-limit":{"description":"Ceiling for the rate-limit window this request charged. Present on responses made with an API key against a rate-limited operation, including the `429` itself; absent for user access tokens (which carry no per-key budget) and when the rate-limit backend could not be read.","schema":{"type":"integer"}},"x-ratelimit-remaining":{"description":"Requests left in that window AFTER this one was counted. Pace off this rather than waiting for a `429`.","schema":{"type":"integer"}},"x-ratelimit-reset":{"description":"**Seconds from now** until that window resets (a delta, NOT a Unix timestamp). Measured when the response is written. Omitted on the rare occasion the reset instant could not be read, while `limit` and `remaining` are still published.","schema":{"type":"integer"}}},"exampleType":"generated"}},"security":{"51753f64-6d01-460b-88c8-b6c4af155f1f":{"bearerAuth":{"description":"Workspace API key as a bearer token: `Authorization: Bearer ish_sk_live_...`. Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: `sessions:run` (create a session, submit turns, close), `sessions:read` (read the session and its decision trace), `environments:read` and `environments:write` (manage the workspace's registered environments), `tasks:read` and `tasks:write` (manage the workspace's registered tasks), `people:read` and `people:write` (the people the workspace can run a session for), and `usage:read` (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with `sessions:run`, `sessions:read`, and `tasks:read` by default; every other scope must be requested, `people:read` and `usage:read` included. An ish user access token also works on the same header for personal scripts.","scheme":"bearer","type":"http","scopes":[],"schemeName":"bearerAuth"}}},"servers":{"22c3a961-b6d9-4922-b5aa-d0aac292aa39":{"description":"Production","url":"https://api.ishlabs.io"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"description":"Workspace API key as a bearer token: `Authorization: Bearer ish_sk_live_...`. Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: `sessions:run` (create a session, submit turns, close), `sessions:read` (read the session and its decision trace), `environments:read` and `environments:write` (manage the workspace's registered environments), `tasks:read` and `tasks:write` (manage the workspace's registered tasks), `people:read` and `people:write` (the people the workspace can run a session for), and `usage:read` (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with `sessions:run`, `sessions:read`, and `tasks:read` by default; every other scope must be requested, `people:read` and `usage:read` included. An ish user access token also works on the same header for personal scripts.","scheme":"bearer","type":"http","scopes":[],"schemeName":"bearerAuth"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"Workspace API key as a bearer token: `Authorization: Bearer ish_sk_live_...`. Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: `sessions:run` (create a session, submit turns, close), `sessions:read` (read the session and its decision trace), `environments:read` and `environments:write` (manage the workspace's registered environments), `tasks:read` and `tasks:write` (manage the workspace's registered tasks), `people:read` and `people:write` (the people the workspace can run a session for), and `usage:read` (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with `sessions:run`, `sessions:read`, and `tasks:read` by default; every other scope must be requested, `people:read` and `usage:read` included. An ish user access token also works on the same header for personal scripts.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"bearerAuth","name":"Authorization"}],"title":"bearerAuth"}]},"originalFileLocation":"api/openapi.public.json"},"subdomain":"ish","siteName":"ish","title":"Create Task - ish","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-08T15:42:21.290Z","originalFileLocation":"api/reference/tasks/create-task.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Register a task: a named intent a session can bind by id. Registering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409. get_or_create is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer Idempotency-Key for retries and PATCH to reconcile content.\">\u003cmeta data-mint-head name=\"application-name\" content=\"ish\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create Task - ish\">\u003cmeta data-mint-head property=\"og:description\" content=\"Register a task: a named intent a session can bind by id. Registering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409. get_or_create is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer Idempotency-Key for retries and PATCH to reconcile content.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"ish\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.ishlabs.io/api/reference/tasks/create-task\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://ish.mintlify.site/_mintlify/api/og/v2?division=API+reference\u0026amp;title=Create+Task\u0026amp;description=Register+a+task%3A+a+named+intent+a+session+can+bind+by+id.%0A%0ARegistering+is+optional.+Do+it+when+runs+have+to+stay+comparable+across+a+boundary+the+session+itself\u0026amp;theme=e052e8dabadef59794361480\u0026amp;signature=c4b62e4c51ada451b8b92d510c34d3c8e475d1bef0d1b38e3d125de605c2fe89\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create Task - ish\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Register a task: a named intent a session can bind by id. Registering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409. get_or_create is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer Idempotency-Key for retries and PATCH to reconcile content.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://ish.mintlify.site/_mintlify/api/og/v2?division=API+reference\u0026amp;title=Create+Task\u0026amp;description=Register+a+task%3A+a+named+intent+a+session+can+bind+by+id.%0A%0ARegistering+is+optional.+Do+it+when+runs+have+to+stay+comparable+across+a+boundary+the+session+itself\u0026amp;theme=e052e8dabadef59794361480\u0026amp;signature=c4b62e4c51ada451b8b92d510c34d3c8e475d1bef0d1b38e3d125de605c2fe89\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/ish/pQaVEm2sa1ahpXnl/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"ish\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#C8623F\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.ishlabs.io/api/reference/tasks/create-task\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/reference/tasks/create-task.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.ishlabs.io/#organization\",\"name\":\"ish\",\"url\":\"https://docs.ishlabs.io\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/ish/4MaJn6-B7_NnPAml/logo/light.svg?fit=max\u0026auto=format\u0026n=4MaJn6-B7_NnPAml\u0026q=85\u0026s=f0edab6b74c19bec95794ee94d7270c2\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.ishlabs.io#website\",\"name\":\"ish\",\"url\":\"https://docs.ishlabs.io\",\"publisher\":{\"@id\":\"https://docs.ishlabs.io/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.ishlabs.io/api/reference/tasks/create-task#webpage\",\"url\":\"https://docs.ishlabs.io/api/reference/tasks/create-task\",\"name\":\"Create Task\",\"description\":\"Register a task: a named intent a session can bind by id. Registering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409. get_or_create is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer Idempotency-Key for retries and PATCH to reconcile content.\",\"dateModified\":\"2026-10-08T15:42:21.290Z\",\"isPartOf\":{\"@id\":\"https://docs.ishlabs.io#website\"},\"breadcrumb\":{\"@id\":\"https://docs.ishlabs.io/api/reference/tasks/create-task#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.ishlabs.io/api/reference/tasks/create-task#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"API reference\",\"item\":\"https://docs.ishlabs.io/api/reference/introduction\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create Task\",\"item\":\"https://docs.ishlabs.io/api/reference/tasks/create-task\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.ishlabs.io/api/reference/tasks/create-task#apireference\",\"headline\":\"Create Task\",\"name\":\"Create Task\",\"description\":\"Register a task: a named intent a session can bind by id. Registering is optional. Do it when runs have to stay comparable across a boundary the session itself cannot draw, such as the same task across two environments or across a month of builds. A one-off task belongs inline on the session. Send an Idempotency-Key header to make retries safe: the same key with the same body replays the original task as a 200, and the same key with a different body is a 409. get_or_create is the older, coarser flag and still works. Note what it does NOT do: on a name match it returns the existing task untouched and ignores every other field you sent, so a request whose instructions have drifted succeeds while changing nothing. Prefer Idempotency-Key for retries and PATCH to reconcile content.\",\"url\":\"https://docs.ishlabs.io/api/reference/tasks/create-task\",\"mainEntityOfPage\":{\"@id\":\"https://docs.ishlabs.io/api/reference/tasks/create-task#webpage\"},\"dateModified\":\"2026-10-08T15:42:21.290Z\",\"publisher\":{\"@id\":\"https://docs.ishlabs.io/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.ishlabs.io#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"ish\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"ish","nav":{"global":{"anchors":[{"anchor":"GitHub","icon":"github","href":"https://github.com/ishlabs"},{"anchor":"ishlabs.io","icon":"globe","href":"https://ishlabs.io"}]},"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"CLI Reference","pages":[{"title":"CLI Reference","href":"/cli/overview"}]},{"tab":"MCP Reference","pages":[{"title":"MCP Reference","href":"/mcp/overview"}]},{"tab":"API","groups":[{"group":"Get started","pages":[{"title":"The ish API","mode":"explanation","href":"/api/overview"},{"title":"Quickstart","mode":"tutorial","href":"/api/quickstart"},{"title":"Authentication","mode":"how-to","href":"/api/authentication"}]},{"group":"Core concepts","pages":[{"title":"Sessions and turns","mode":"explanation","href":"/api/concepts/sessions-and-turns"},{"title":"Observations","mode":"explanation","href":"/api/concepts/observations"},{"title":"The decide-only loop","mode":"explanation","href":"/api/concepts/decide-only-loop"},{"title":"Intent and resolution","mode":"explanation","href":"/api/concepts/intent-and-resolution"},{"title":"People","mode":"explanation","href":"/api/concepts/people"}]},{"group":"Guides","pages":[{"title":"Run the session loop","mode":"how-to","href":"/api/guides/session-loop"},{"title":"Author your environment","mode":"how-to","href":"/api/guides/environment-authoring"},{"title":"Score outcomes","mode":"how-to","href":"/api/guides/scoring-outcomes"},{"title":"Search people","mode":"how-to","href":"/api/guides/people-search"}]},{"group":"API reference","pages":[{"title":"API reference","mode":"reference","href":"/api/reference/introduction"},{"title":"Errors","mode":"reference","href":"/api/errors"},{"title":"Create Session","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/workspaces/{workspace_id}/sessions","href":"/api/reference/sessions/create-session"},{"title":"List Sessions","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/workspaces/{workspace_id}/sessions","href":"/api/reference/sessions/list-sessions"},{"title":"Submit Turn","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/sessions/{session_id}/turns","href":"/api/reference/sessions/submit-turn"},{"title":"Get Session","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/sessions/{session_id}","href":"/api/reference/sessions/get-session"},{"title":"Close Session","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/sessions/{session_id}/close","href":"/api/reference/sessions/close-session"},{"title":"Create Environment","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/workspaces/{workspace_id}/environments","href":"/api/reference/environments/create-environment"},{"title":"List Environments","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/workspaces/{workspace_id}/environments","href":"/api/reference/environments/list-environments"},{"title":"Get Environment","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/environments/{environment_id}","href":"/api/reference/environments/get-environment"},{"title":"Update Environment","deprecated":null,"version":null,"openapi":"/api/openapi.public.json patch /api/v1/environments/{environment_id}","href":"/api/reference/environments/update-environment"},{"title":"Delete Environment","deprecated":null,"version":null,"openapi":"/api/openapi.public.json delete /api/v1/environments/{environment_id}","href":"/api/reference/environments/delete-environment"},{"title":"Create Environment Version","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/environments/{environment_id}/versions","href":"/api/reference/environments/create-environment-version"},{"title":"List Environment Versions","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/environments/{environment_id}/versions","href":"/api/reference/environments/list-environment-versions"},{"title":"Get Environment Version","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/environment-versions/{version_id}","href":"/api/reference/environments/get-environment-version"},{"title":"Update Environment Version","deprecated":null,"version":null,"openapi":"/api/openapi.public.json patch /api/v1/environment-versions/{version_id}","href":"/api/reference/environments/update-environment-version"},{"title":"Delete Environment Version","deprecated":null,"version":null,"openapi":"/api/openapi.public.json delete /api/v1/environment-versions/{version_id}","href":"/api/reference/environments/delete-environment-version"},{"title":"Set Default Environment Version","description":"Point this environment's default at this variant.\n\nSessions that name the environment WITHOUT pinning a version resolve here\nfrom now on. Sessions already opened are untouched: the version they ran\nagainst is stamped on the row and nothing re-resolves it.\n\nIdempotent, and the outgoing default is cleared in the same transaction.","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/environment-versions/{version_id}/set-default","href":"/api/reference/environments/set-default-environment-version"},{"title":"Create Task","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/workspaces/{workspace_id}/tasks","href":"/api/reference/tasks/create-task"},{"title":"List Tasks","description":"List the workspace's registered tasks, oldest first.","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/workspaces/{workspace_id}/tasks","href":"/api/reference/tasks/list-tasks"},{"title":"Get Task","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/tasks/{task_id}","href":"/api/reference/tasks/get-task"},{"title":"Update Task","deprecated":null,"version":null,"openapi":"/api/openapi.public.json patch /api/v1/tasks/{task_id}","href":"/api/reference/tasks/update-task"},{"title":"Delete Task","deprecated":null,"version":null,"openapi":"/api/openapi.public.json delete /api/v1/tasks/{task_id}","href":"/api/reference/tasks/delete-task"},{"title":"List People","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/workspaces/{workspace_id}/people","href":"/api/reference/people/list-people"},{"title":"Search People","deprecated":null,"version":null,"openapi":"/api/openapi.public.json post /api/v1/workspaces/{workspace_id}/people/search","href":"/api/reference/people/search-people"},{"title":"Get Person","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/workspaces/{workspace_id}/people/{person_id}","href":"/api/reference/people/get-person"},{"title":"Get People Counts","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/workspaces/{workspace_id}/people/counts","href":"/api/reference/people/get-people-counts"},{"title":"Get People Schema","deprecated":null,"version":null,"openapi":"/api/openapi.public.json get /api/v1/workspaces/{workspace_id}/people/schema","href":"/api/reference/people/get-people-schema"}]},{"group":"Versioning and changes","pages":[{"title":"Versioning and deprecation","mode":"reference","href":"/api/versioning"},{"title":"Changelog","mode":"reference","href":"/api/changelog"}]}]},{"tab":"Help","pages":[{"title":"Help","href":"/help/troubleshooting"}]}]},"basePath":"","title":"Create Task - ish","buildId":"dpl_42LwxxU1kGN114H4XzwGYXa9ZDah","deploymentId":"dpl_42LwxxU1kGN114H4XzwGYXa9ZDah","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-C-hEh3I2.js","utils-CnF4QiUD.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-C7PVNbel.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-8ytevL2A.js","snippetPresets-BT1alx3v.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-BLXC0i_W.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-CyLIGI9_.js","shallow-DC0lGVIW.js","getApiPlaygroundDisplay-CgDQ85tN.js","CodeSnippet-6-I-Gpv9.js","CodeSnippets-BAk1kDdu.js","Page-C945cI-W.js","getPastedJson-B276RuWN.js","icon-BqP8etTm.js","MethodPill-DM6sbxG1.js","DuplicateIcon-PyJglOaE.js","createIcon-CMeOMAc_.js","DynamicMarkdown-BoyYAA8K.js","SectionHeading-DAYv3gvZ.js","axios-vUo_bRtp.js","Markdown-BhTTmazV.js","clsx-CR-RHrVC.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-CBUH0-zX.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-BmARFYNC.js"]}