API ReferenceTasks

Create a New Task

Create a new Task with specified prompts, model configuration, and output format. Tasks are the core building blocks that define how the LLM processes inputs and generates structured outputs. Each Task includes: - System and user prompts that guide the LLM's behavior - Input parameters that can be dynamically provided when running the Task - Output format specification that ensures consistent, structured responses - Output modality (JSON, image, or audio generation) - Optional fallback model for improved reliability when primary model fails - Optional task run visibility controls for managing access to task execution history - Optional image processing capabilities - Optional RAG (Retrieval Augmented Generation) for domain-specific knowledge Task Run Visibility: - `owner_only` (default): Only task owners can view all task runs - `editors_and_owners`: Task editors and owners can view all task runs - `all_viewers`: All users with view permission can see all task runs The Task will be created with an initial revision that becomes automatically active.

Authentication

AuthorizationBearer

Bearer token authentication using JWT tokens from Ory Kratos/Hydra

Path Parameters

org_idstringRequiredformat: "uuid"
The unique identifier of the organization.
project_idstringRequiredformat: "uuid"
The unique identifier of the project.

Request

This endpoint expects an object.
system_promptstringRequired
The system prompt that is used to set the LLM context.
user_promptstringRequired

The description of the Task. It is not required to mention the outputs in the prompt, but it can help the model to understand the context better. Any input strings should be referenced with the dynamic {...} syntax, this informs the model to look for those values in the input data.

llm_model_idstringRequiredformat: "uuid"
The LLM model to use for the Task.
namestringRequiredformat: "^[a-zA-Z0-9\- ]+$"
A name or reference for the Task.
enabledbooleanRequired

When true the Task is active and callable. false denotes the Task is not yet operational.

llm_configmap from strings to anyOptional
Specific configuration parameters for the LLM model.
output_formatmap from strings to objects or enums or nullOptional

This gives control over the structure of how the Task responds. Supports shorthand notation or an object with type can be specified for each attribute. In most instances, the LLM will be able to generate the desired output into the relevant property, but an optional description can be passed to provide it with additional context.

task_forwarder_idstring or nullOptionalformat: "uuid"
The unique identifier for a valid Task Forwarder. It is used to forward the Task output to another system or service.
ragobject or nullOptional

Note: This is a Paid Tier feature. Provide additional domain specific input to the LLM so that it is able to reference user specific information when executing the Task. Examples of this could be a product catalogue, terms and conditions or a user manual.

image_requiredbooleanOptionalDefaults to false

When true it requires an image to be sent in the Task Run request.

optimise_imagesbooleanOptionalDefaults to true

When true (default) images will be automatically optimised before processing. Set to false to disable lossy image optimisation.

testbooleanOptionalDefaults to false

True if revision is a test revision. Test revisions cannot be live and are used for rapid Task testing/iteration.

input_processorslist of objectsOptional
annotationstring or nullOptional<=255 characters
Optional note or comment about this revision. Useful for tracking changes, experiments, or the purpose of test revisions.
fallback_llm_model_idstring or nullOptionalformat: "uuid"
The LLM model to use as fallback if the primary model fails.
fallback_llm_configmap from strings to any or nullOptional
Specific configuration parameters for the fallback LLM model.
descriptionstring or nullOptional
A longer description of the Task for internal reference.
publicbooleanOptionalDefaults to false

When true the Task is public and can be accessed by any User.

exposed_to_agentsbooleanOptionalDefaults to false

When true the Task is accessible to agents through the unauthenticated agent endpoint.

output_modalityenumOptionalDefaults to json
Specifies the output modality of the task. Can be 'json' or 'image'. Defaults to 'json'.
Allowed values:
task_run_visibilityenumOptionalDefaults to owner_only

Controls who can view all task runs. ‘owner_only’ - only task owners see all runs (default), ‘editors_and_owners’ - task editors and owners see all runs, ‘all_viewers’ - all users with view permission see all runs.

Allowed values:

Response

Successful Response
namestringformat: "^[a-zA-Z0-9\- ]+$"
A name or reference for the Task.
enabledboolean

When true the Task is active and callable. false denotes the Task is not yet operational.

idstringformat: "uuid"
The unique identifier of the Task.
project_idstringformat: "uuid"
The Project that the Task belongs to.
createdstring
When the Task was created.
access_tokenstring or null
Task specific Bearer token that can be used to authenticated when executing this Task.
active_revisionslist of objects
The revision currently active for this Task.
descriptionstring or null
A longer description of the Task for internal reference.
publicboolean or nullDefaults to false

When true the Task is public and can be accessed by any User.

exposed_to_agentsboolean or nullDefaults to false

When true the Task is accessible to agents through the unauthenticated agent endpoint.

output_modalityenum or nullDefaults to json
Specifies the output modality of the task. Can be 'json' or 'image'. Defaults to 'json'.
Allowed values:
task_run_visibilityenum or nullDefaults to owner_only

Controls who can view all task runs. ‘owner_only’ - only task owners see all runs (default), ‘editors_and_owners’ - task editors and owners see all runs, ‘all_viewers’ - all users with view permission see all runs.

Allowed values:
modifiedstring or null
When the Task was last updated.
revisionslist of objects or null

Each update to a Task results in a new Revision being created. Task Revisions are a powerful concept that can be used to assist with A/B testing, comparing responses from different LLM’s, etc.

cloned_from_task_revision_idstring or nullformat: "uuid"
The unique identifier of the task revision this task was cloned from, if applicable.
tagslist of objects or null

Errors