Documentation - Request Object

Request object

The only required field needed for an API request is the request field. In this field, you can actually make your full request, pass additional context, etc. and have it parsed by DZ's API.

However, additional properties can be added to the request for greater specificity, direction and clarity - context and instructions.

request = the human-readable required intent
context = evidence/facts for this specific request
instructions = behavioral controls for the request

While request is a standard string field on the root level of the request, context and instructions are objects each containing their own list of optional properties. By default, DZ will use the information saved in your acccount's context to handle responses, however, that behavior can be overwritten based on what's passed in an individual request.

Mode

By default, DelegateZero processes decisions asynchronously - your POST returns immediately and you poll for the result. Add "mode": "sync" to receive the complete decision in a single response instead.

Field

Type

Values

Definition

mode

string

async, sync

Processing mode. async (default) returns immediately and requires polling. sync returns the full result in one response, but consults fewer context entries and skips live source data.

Profile

Include a profile field to route the decision against a specific profile's context, policies, and confidence threshold. If omitted, the user's default profile or workspace default is used. See Profiles for details.

Field

Type

Values

Definition

profile

string

profile slug

The slug of the profile to run this decision against. Returns 403 if the API key's user is not assigned to the specified profile.

Context property

Here is a full list of the possible properties in the context object:

Field

Type

Values

Definition

source

string

any

Where the request is coming from (e.g. slack, email)

type

string

any

High-level category (e.g. client email, approval, report generation, routing)

entity

string

any

Entities involved (e.g. client, person)

data

string

any

Raw message or content referenced in the request (e.g. email body, ticket information)

Instructions property

Here is a full list of the possible properties in the instructions object:

Field

Type

Values

Definition

confidence_threshold

number

0.0-1.0

Minimum confidence required to return a decision='execute'. Otherwise draft or escalate.

format

string

text, markdown, html, json

Preferred format for the response value.

tone

string

neutral, friendly, formal, direct

Nudges writing style

max_length

number

any

Soft cap on response length in terms of characters.

attribution

string

user, assistant

Whether the response should be framed as coming from you or your assistant.

response_schema

object

any

Key/value object of field names and descriptions to split the response into specific fields (e.g. {"subject": "Email subject line", "html": "Full HTML email body"}).

dry_run

boolean

true/false

If true, the request won't execute any external actions, only returns what it would do to be audited in the dashboard.

Pinning context

By default, DelegateZero searches your full context library to find the most relevant entries for each request. If you already know exactly which context entries apply, you can pin them explicitly using the context_ids parameter:

{
  "request": "Should we approve this vendor invoice?",
  "context_ids": [42, 107, 318]
}

When context_ids is provided, DelegateZero skips the relevance search entirely and consults only those entries. This is useful when your integration knows the exact policies, entities, or playbooks that govern a decision - it produces faster, more deterministic results and a cleaner audit trail.

Context IDs are visible in the ID column on each context page (Policies, Entities, Playbooks, etc.). An empty context_ids array is treated the same as omitting the parameter.

Examples

Below are some examples of API requests including a mix-and-match of various properties.

Structured output for downstream automation:

cURL

Node.js

Python

        curl -X POST https://delegatezero.com/api/v1/decisions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Draft a client update about this month's analytics.",
    "context": {
      "entity": "ABC Company",
      "data": "Organic traffic up 12%, paid traffic down after campaign pause."
    },
    "instructions": {
      "response_schema": {
        "subject": "Email subject line",
        "html": "Full HTML email body",
        "text": "Plain text version of the email"
      }
    }
  }'

        import axios from "axios";

const decision = await axios.post(
  "https://delegatezero.com/api/v1/decisions",
  {
    request: "Draft a client update about this month's analytics.",
    context: {
      entity: "ABC Company",
      data: "Organic traffic up 12%, paid traffic down after campaign pause."
    },
    instructions: {
      response_schema: {
        subject: "Email subject line",
        html: "Full HTML email body",
        text: "Plain text version of the email"
      }
    }
  },
  {
    headers: {
      Authorization: `Bearer ${process.env.API_KEY}`
    }
  }
);

        import requests
import os

response = requests.post(
  "https://delegatezero.com/api/v1/decisions",
  headers={
    "Authorization": "Bearer {os.environ['API_KEY']}",
    "Content-Type": "application/json"
  },
  json={
    "request": "Draft a client update about this month's analytics.",
    "context": {
      "entity": "ABC Company",
      "data": "Organic traffic up 12%, paid traffic down after campaign pause."
    },
    "instructions": {
      "response_schema": {
        "subject": "Email subject line",
        "html": "Full HTML email body",
        "text": "Plain text version of the email"
      }
    }
  }
)

Responding to an internal message with confidence control:

cURL

Node.js

Python

        curl -X POST https://delegatezero.com/api/v1/decisions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Respond to this internal Slack message.",
    "context": {
      "source": "slack",
      "data": "Can we commit to having this ready by Friday?"
    },
    "instructions": {
      "confidence_threshold": 0.85,
      "tone": "direct"
    }
  }'

        import axios from "axios";

const decision = await axios.post(
  "https://delegatezero.com/api/v1/decisions",
  {
    request: "Respond to this internal Slack message.",
    context: {
      source: "slack",
      data: "Can we commit to having this ready by Friday?"
    },
    instructions: {
      confidence_threshold: 0.85,
      tone: "direct"
    }
  },
  {
    headers: {
      Authorization: `Bearer ${process.env.API_KEY}`
    }
  }
);

        import requests
import os

response = requests.post(
  "https://delegatezero.com/api/v1/decisions",
  headers={
    "Authorization": "Bearer {os.environ['API_KEY']}",
    "Content-Type": "application/json"
  },
  json={
    "request": "Respond to this internal Slack message.",
    "context": {
      "source": "slack",
      "data": "Can we commit to having this ready by Friday?"
    },
    "instructions": {
      "confidence_threshold": 0.85,
      "tone": "direct"
    }
  }
)

Safe evaluation with dry run and strict mode:

cURL

Node.js

Python

        curl -X POST https://delegatezero.com/api/v1/decisions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Approve this customer exception request.",
    "context": {
      "entity": "XYZ Startup",
      "data": "Asking for a one-time pricing exception."
    },
    "instructions": {
      "dry_run": true
    }
  }'

        import axios from "axios";

const decision = await axios.post(
  "https://delegatezero.com/api/v1/decisions",
  {
    request: "Approve this customer exception request.",
    context: {
      entity: "XYZ Startup",
      data: "Asking for a one-time pricing exception."
    },
    instructions: {
      dry_run: true
    }
  },
  {
    headers: {
      Authorization: `Bearer ${process.env.API_KEY}`
    }
  }
);

        import requests
import os

response = requests.post(
  "https://delegatezero.com/api/v1/decisions",
  headers={
    "Authorization": "Bearer {os.environ['API_KEY']}",
    "Content-Type": "application/json"
  },
  json={
    "request": "Approve this customer exception request.",
    "context": {
      "entity": "XYZ Startup",
      "data": "Asking for a one-time pricing exception."
    },
    "instructions": {
      "dry_run": true
    }
  }
)

Async polling

By default, decision requests are processed asynchronously (see "mode" above). Your POST returns immediately with a pending status and an ID. Poll GET /api/v1/decisions/{id} every 2-3 seconds until status is complete.

cURL

Node.js

Python

        # Step 1: Submit the decision request
RESPONSE=$(curl -s -X POST https://delegatezero.com/api/v1/decisions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": "Draft a monthly analytics update for ABC Company.",
    "context": { "entity": "ABC Company" }
  }')

ID=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Step 2: Poll until complete
while true; do
  RESULT=$(curl -s "https://delegatezero.com/api/v1/decisions/$ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo $RESULT | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  if [ "$STATUS" = "complete" ]; then
    echo "$RESULT"
    break
  fi
  sleep 2.5
done

        import axios from "axios";

const headers = { Authorization: `Bearer ${process.env.API_KEY}` };

// Step 1: Submit the decision request
const { data: pending } = await axios.post(
  "https://delegatezero.com/api/v1/decisions",
  {
    request: "Draft a monthly analytics update for ABC Company.",
    context: { entity: "ABC Company" }
  },
  { headers }
);

// Step 2: Poll until complete
async function pollDecision(id) {
  while (true) {
    const { data } = await axios.get(
      `https://delegatezero.com/api/v1/decisions/${id}`,
      { headers }
    );
    if (data.status === "complete") return data;
    await new Promise(r => setTimeout(r, 2500));
  }
}

const decision = await pollDecision(pending.id);
console.log(decision);

        import requests
import time
import os

headers = {
  "Authorization": f"Bearer {os.environ['API_KEY']}",
  "Content-Type": "application/json"
}

# Step 1: Submit the decision request
response = requests.post(
  "https://delegatezero.com/api/v1/decisions",
  headers=headers,
  json={
    "request": "Draft a monthly analytics update for ABC Company.",
    "context": { "entity": "ABC Company" }
  }
)

decision_id = response.json()["id"]

# Step 2: Poll until complete
while True:
  result = requests.get(
    f"https://delegatezero.com/api/v1/decisions/{decision_id}",
    headers=headers
  ).json()
  if result["status"] == "complete":
    print(result)
    break
  time.sleep(2.5)

There are no results for that search on this page, however, if you press the enter key then our entire documentation will be searched and you will receive the results. If you need assistance, please contact us.