Skip to content
KataraKatara documentation

Set up a first agent and start its first run

POST
/katara/v1/orgs/{org_id}/environments/{environment_id}/setup
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/setup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "starter": "assistant", "instructions": "example", "first_task": "example" }'

Requires an owner or admin in a signed-in session, in a Test environment. Creates an agent, uses or creates a content store, activates a starter policy when the environment has none, writes the starter’s instructions, schemas and first input, funds a one-credit budget for thirty days, issues the grants a run needs, publishes the agent’s first version, gives it read access to that version’s content and admits a first run. Each finished step is kept. A person has one setup under way per environment: starting again with the same request continues it whatever the idempotency key, a different request answers setup_in_progress until it finishes or is discarded, and a repeated key returns its own setup once finished. An interruption such as a stale sign-in or access not yet delivered is returned as an error.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
/^[A-Za-z0-9._:-]{8,128}$/
X-Katara-CSRF
Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

The starter agent to set up. A blank agent also carries the instructions and first task the person wrote. The documents starter may carry a first task, the question it answers from its sample documents, and the approval starter the task its approved model call carries out. The other starters carry neither.

object
starter
required
Allowed values: assistant summarizer blank documents approval
instructions
string
>= 1 characters <= 32768 characters
first_task
string
>= 1 characters <= 4000 characters

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json

How far a setup has come and the request it was started with. A setup is done once its first run is admitted and discarded once its person gives it up; while running, starting again with the same request continues it.

object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
starter
required
Allowed values: assistant summarizer blank documents approval
request
required

The starter agent to set up. A blank agent also carries the instructions and first task the person wrote. The documents starter may carry a first task, the question it answers from its sample documents, and the approval starter the task its approved model call carries out. The other starters carry neither.

object
starter
required
Allowed values: assistant summarizer blank documents approval
instructions
string
>= 1 characters <= 32768 characters
first_task
string
>= 1 characters <= 4000 characters
state
required
Allowed values: running done discarded
steps
required
Array<object>
>= 9 items <= 9 items

One step of a setup and whether it has finished.

object
name
required
Allowed values: agent storage policy approval_policy documents knowledge budget grants agent_version content_access first_run
done
required
boolean
agent_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
run_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
restore_policy

For the approval starter, the policy it replaced; activate it again to stop asking approval for every model call.

object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
started_at
required
string format: date-time
Example
{
  "starter": "assistant",
  "request": {
    "starter": "assistant"
  },
  "state": "running",
  "steps": [
    {
      "name": "agent"
    }
  ]
}

409

Section titled “409”

Account_changed: reload and review with the signed-in account.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}