Use tasks

A task is one thing your app asks a model to do, such as summarising a note or answering a support question. You set it up once in the console: the prompt, the model, how long an answer may be, and how much text a call may send. Your code sends only the task’s name and the input.

Use a task when:

• The same task runs again and again, and you want to change its prompt or model without deploying your app.
• You want every call to cost at most a known amount. A task fixes the most a call can use, and the console shows it.
• Others send the input, such as your app’s users. A task takes their text as input, never as instructions, and cannot be pointed at another model or prompt.

Before you begin

A stored prompt for the task to use. Its variables become the task’s settings or its input.

Create a task

In the console, open the project, then AI, then Tasks, and select New task. Give it:

• A name, such as summarise-note. Your code uses it, so it cannot change later.
• A prompt and its version. The task keeps that version until you move it to another, so saving the prompt never changes a task by surprise. The console shows when a newer version exists.
• A model, and the most tokens an answer may have.
• What a call may send:
  • Input, the text a call sends, up to a number of bytes you choose. Set it to 0 for a task that takes none.
  • Each variable of the prompt, either a fixed value, such as Swahili for {{language}}, or a value the call sends, up to a number of bytes.
  • Earlier messages, for a conversation: how many a call may send, and how many bytes in all. None by default.
• Optional settings: temperature, top P, reasoning effort, and JSON answers, with a JSON schema if you want one.

When you save, the console shows the most one call can use, in tokens and AI units.

Only people with Developer access or more can create, change, or delete tasks. API keys can run them.

Run it

Send the input to the task’s runs:

curl -s "$AI_URL/tasks/summarise-note/runs" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "The ferry to Zanzibar leaves Dar es Salaam at 7:00 and takes 2 hours." }'

{
  "data": {
    "task": "summarise-note",
    "model": "openai/gpt-oss-20b",
    "text": "Kivuko kwenda Zanzibar kinaondoka saa moja asubuhi.",
    "stopReason": "end",
    "usage": { "inputTokens": 58, "outputTokens": 14, "units": 12 }
  }
}

With the SDK:

import { space } from "digitospace"

const reply = await space.ai.run("summarise-note", {
  input: "The ferry to Zanzibar leaves Dar es Salaam at 7:00 and takes 2 hours.",
})
console.log(reply.text)

See Tasks for every field, and run() for the SDK.

What we send the model

• The prompt, filled in with the task’s fixed values and the call’s variables, as the system message.
• The call’s earlier messages, in order.
• The call’s input, as the last user message.

A task that takes no input and no earlier messages sends the filled-in prompt as the user message instead.

A reasoning model’s reasoning is left out of a task’s answer, so text holds only the answer.

JSON answers

Turn on JSON answers to ask the model for a JSON object, and add a JSON schema to describe its shape. The answer then holds json, the parsed object, next to text, and it always matches the schema. When the model cannot give one, the run fails with answer_invalid, or with answer_cut_off when it reached the task’s token limit first. A run that does not stream gets a second try, and both count toward your AI units.

Change a task

Edit it in the console and select Save. The next call uses the change.

• Move to a newer prompt version when you have tested it. Where the new version has other variables, set them in the same save.
• Turn a task off to stop every call to it straight away, without deleting it. Calls to it fail with task_disabled.
• A prompt that a task uses cannot be deleted. Change or delete the task first.

When a run is refused

A run also counts toward the project’s AI limits, like any other call. See Usage and limits.