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

{
  "archived_at": "2023-11-07T05:31:56Z",
  "background": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instructions": "<string>",
  "name": "<string>",
  "revision": 123,
  "steps": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "archived_at": "2023-11-07T05:31:56Z",
  "background": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instructions": "<string>",
  "name": "<string>",
  "revision": 123,
  "steps": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "error": "<string>",
  "error_code": "<string>",
  "errors": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "allowed_values": [
        "<unknown>"
      ],
      "input": "<string>"
    }
  ],
  "retryable": true,
  "status": 123,
  "suggestions": [
    "<string>"
  ]
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

API reference

Create Task

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

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

{
  "archived_at": "2023-11-07T05:31:56Z",
  "background": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instructions": "<string>",
  "name": "<string>",
  "revision": 123,
  "steps": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "archived_at": "2023-11-07T05:31:56Z",
  "background": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "instructions": "<string>",
  "name": "<string>",
  "revision": 123,
  "steps": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z",
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

{
  "detail": "<string>",
  "error": "<string>",
  "error_code": "<string>",
  "errors": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "allowed_values": [
        "<unknown>"
      ],
      "input": "<string>"
    }
  ],
  "retryable": true,
  "status": 123,
  "suggestions": [
    "<string>"
  ]
}

{
  "detail": "<string>",
  "request_id": "<string>",
  "docs_url": "<string>"
}

Authorizations

Authorization

string

header

required

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.

Headers

Idempotency-Key

string | null

Path Parameters

workspace_id

string<uuid>

required

Body

application/json

instructions

string

required

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.

Required string length: 1 - 2000

name

string

required

Required string length: 1 - 120

background

string | null

Background the person is treated as already knowing. Accepted and stored; not yet consumed by API sessions, which currently render the instructions only.

Maximum string length: 8000

get_or_create

boolean

default:false

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.

steps

TaskStep · object[] | null

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.

A registered task as the caller sees it.

archived_at

string<date-time> | null

required

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

string | null

required

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.

created_at

string<date-time>

required

string<uuid>

required

instructions

string

required

name

string

required

revision

integer

required

Increments on every write to this task. Sessions freeze the revision they bound, so runs are comparable within a revision of the content.

steps

TaskStepView · object[] | null

required

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.

Show child attributes

updated_at

string<date-time>

required

workspace_id

string<uuid>

required

Get started

Core concepts

Guides

API reference

Versioning and changes

Create Task

Authorizations

Headers

Path Parameters

Body

Response