Send to human

Use robotrock.sendToHuman() from your shared client module to send an approval request. Set ROBOTROCK_API_KEY in your environment (named keys in Settings → API Keys).

Client setup

// lib/robotrock.ts
import { createClient } from "robotrock";

export const robotrock = createClient({
  app: "my-service",
  version: 2, // optional, default 2
  webhook: {
    url: "https://your-app.com/api/robotrock/webhook",
  },
});

JSON Forms foundation

RobotRock task forms are built on top of JSON Forms concepts:

• JSON Schema defines the structure and validation of response data.
• UI schema controls field rendering (widgets, labels, placeholders, options).

You provide these via action schema and ui fields.

Minimal example

import { robotrock } from "@/lib/robotrock";

const response = await robotrock.sendToHuman({
  type: "budget-approval",
  name: "Approve Q4 budget update",
  actions: [
    { id: "approve", title: "Approve" },
    { id: "reject", title: "Reject" },
  ],
});

Top-level task fields

import { robotrock } from "@/lib/robotrock";

await robotrock.sendToHuman({
  type: "string (required)",
  name: "string (required)",
  description: "string (optional)",
  validUntil: new Date(Date.now() + 2 * 60 * 60 * 1000), // Date or ISO string (optional)
  context: {
    data: {},
    ui: {},
  }, // optional
  actions: [], // required, at least one action
  idempotencyKey: "optional-retry-safe-key",
  assignTo: {
    users: ["alice@acme.com"],
    groups: ["finance"],
  }, // optional — narrows inbox visibility
});

app and version are configured on createClient, not on individual tasks.

Assignment (assignTo)

Optional top-level field (not stored inside task context JSON):

assignTo?: {
  users?: string[];  // tenant member emails
  groups?: string[]; // group slugs, e.g. "finance"
};

Visibility:

• Omitted — task is assigned to the tenant All group; every member sees it.
• Set — only listed users and members of listed groups see the task in the inbox.
• { groups: ["all"] } — same as omitting assignTo.

Invalid emails or unknown group slugs return 400. You cannot combine "all" with other group slugs.

Inbox routing

Set app on createClient to group tasks in the dashboard inbox.

When app is omitted on the client, the API uses your API key name as the inbox bucket.

Webhooks

Configure webhook: { url, headers? } on createClient. The webhook applies to every action. See Webhooks.

Without a webhook, sendToHuman() polls until handled. Set polling on createClient (not on each task). Polling respects each task's validUntil deadline—see Polling.

Split references

• For all context fields and widgets, see Context.
• For complete task payload examples, see Examples under Tasks in the sidebar.
• For all actions fields and examples, see Task Actions.
• For getTask, cancelTask, and task statuses, see Task lifecycle.