# Workers ## Create a worker `client.workers.create(WorkerCreateParamsbody, RequestOptionsoptions?): Worker` **post** `/api/workers` Create a new agent worker and start it with the supplied instruction. ### Parameters - `body: WorkerCreateParams` - `input: string` - `budget?: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `stream?: boolean` ### Returns - `Worker` - `id: string` - `created_at: number | null` - `error: unknown` - `files: Array` - `filename: string | null` - `mediaType: string` - `url: string` - `incomplete_details: unknown` - `messages: Array` - `metadata: Record` - `object: "worker"` - `"worker"` - `output: Array` - `id: string` - `content: Array` - `text: string` - `type: "output_text"` - `"output_text"` - `role: "assistant"` - `"assistant"` - `status: "completed"` - `"completed"` - `type: "message"` - `"message"` - `output_text: string` - `running: boolean` - `sources: Array` - `id: string` - `title: string | null` - `type: "url"` - `"url"` - `url: string` - `status: "running" | "completed" | "pending"` - `"running"` - `"completed"` - `"pending"` - `costs?: Costs | null` - `internalCostUsd: number` - `modelCostUsd: number` - `sandboxCostUsd: number` - `toolCostUsd: number` - `usage?: Usage` - `cacheReadTokens: number` - `cacheWriteTokens: number` - `costUsd: number` - `inputTokens: number` - `outputTokens: number` - `reasoningTokens: number` - `steps: number` - `totalTokens: number` - `credits?: number` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const worker = await client.workers.create({ input: 'x' }); console.log(worker.id); ``` #### Response ```json { "id": "id", "created_at": 0, "error": null, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "url" } ], "incomplete_details": null, "messages": [ {} ], "metadata": { "foo": "bar" }, "object": "worker", "output": [ { "id": "id", "content": [ { "text": "text", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "output_text": "output_text", "running": true, "sources": [ { "id": "id", "title": "title", "type": "url", "url": "url" } ], "status": "running", "costs": { "internalCostUsd": 0, "modelCostUsd": 0, "sandboxCostUsd": 0, "toolCostUsd": 0 }, "usage": { "cacheReadTokens": 0, "cacheWriteTokens": 0, "costUsd": 0, "inputTokens": 0, "outputTokens": 0, "reasoningTokens": 0, "steps": 0, "totalTokens": 0, "credits": 0 } } ``` ## Retrieve a worker `client.workers.retrieve(stringworkerID, WorkerRetrieveParamsquery?, RequestOptionsoptions?): Worker` **get** `/api/workers/{workerId}` Retrieve the current worker state. Pass stream=true or request text/event-stream to subscribe to updates. ### Parameters - `workerID: string` - `query: WorkerRetrieveParams` - `stream?: boolean` Return a server-sent event stream instead of JSON. ### Returns - `Worker` - `id: string` - `created_at: number | null` - `error: unknown` - `files: Array` - `filename: string | null` - `mediaType: string` - `url: string` - `incomplete_details: unknown` - `messages: Array` - `metadata: Record` - `object: "worker"` - `"worker"` - `output: Array` - `id: string` - `content: Array` - `text: string` - `type: "output_text"` - `"output_text"` - `role: "assistant"` - `"assistant"` - `status: "completed"` - `"completed"` - `type: "message"` - `"message"` - `output_text: string` - `running: boolean` - `sources: Array` - `id: string` - `title: string | null` - `type: "url"` - `"url"` - `url: string` - `status: "running" | "completed" | "pending"` - `"running"` - `"completed"` - `"pending"` - `costs?: Costs | null` - `internalCostUsd: number` - `modelCostUsd: number` - `sandboxCostUsd: number` - `toolCostUsd: number` - `usage?: Usage` - `cacheReadTokens: number` - `cacheWriteTokens: number` - `costUsd: number` - `inputTokens: number` - `outputTokens: number` - `reasoningTokens: number` - `steps: number` - `totalTokens: number` - `credits?: number` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const worker = await client.workers.retrieve('t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM'); console.log(worker.id); ``` #### Response ```json { "id": "id", "created_at": 0, "error": null, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "url" } ], "incomplete_details": null, "messages": [ {} ], "metadata": { "foo": "bar" }, "object": "worker", "output": [ { "id": "id", "content": [ { "text": "text", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "output_text": "output_text", "running": true, "sources": [ { "id": "id", "title": "title", "type": "url", "url": "url" } ], "status": "running", "costs": { "internalCostUsd": 0, "modelCostUsd": 0, "sandboxCostUsd": 0, "toolCostUsd": 0 }, "usage": { "cacheReadTokens": 0, "cacheWriteTokens": 0, "costUsd": 0, "inputTokens": 0, "outputTokens": 0, "reasoningTokens": 0, "steps": 0, "totalTokens": 0, "credits": 0 } } ``` ## Continue a worker `client.workers.continue(stringworkerID, WorkerContinueParamsbody, RequestOptionsoptions?): Worker` **post** `/api/workers/{workerId}` Send another instruction to an existing worker. ### Parameters - `workerID: string` - `body: WorkerContinueParams` - `input: string` - `budget?: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `stream?: boolean` ### Returns - `Worker` - `id: string` - `created_at: number | null` - `error: unknown` - `files: Array` - `filename: string | null` - `mediaType: string` - `url: string` - `incomplete_details: unknown` - `messages: Array` - `metadata: Record` - `object: "worker"` - `"worker"` - `output: Array` - `id: string` - `content: Array` - `text: string` - `type: "output_text"` - `"output_text"` - `role: "assistant"` - `"assistant"` - `status: "completed"` - `"completed"` - `type: "message"` - `"message"` - `output_text: string` - `running: boolean` - `sources: Array` - `id: string` - `title: string | null` - `type: "url"` - `"url"` - `url: string` - `status: "running" | "completed" | "pending"` - `"running"` - `"completed"` - `"pending"` - `costs?: Costs | null` - `internalCostUsd: number` - `modelCostUsd: number` - `sandboxCostUsd: number` - `toolCostUsd: number` - `usage?: Usage` - `cacheReadTokens: number` - `cacheWriteTokens: number` - `costUsd: number` - `inputTokens: number` - `outputTokens: number` - `reasoningTokens: number` - `steps: number` - `totalTokens: number` - `credits?: number` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const worker = await client.workers.continue('t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM', { input: 'x', }); console.log(worker.id); ``` #### Response ```json { "id": "id", "created_at": 0, "error": null, "files": [ { "filename": "filename", "mediaType": "mediaType", "url": "url" } ], "incomplete_details": null, "messages": [ {} ], "metadata": { "foo": "bar" }, "object": "worker", "output": [ { "id": "id", "content": [ { "text": "text", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "output_text": "output_text", "running": true, "sources": [ { "id": "id", "title": "title", "type": "url", "url": "url" } ], "status": "running", "costs": { "internalCostUsd": 0, "modelCostUsd": 0, "sandboxCostUsd": 0, "toolCostUsd": 0 }, "usage": { "cacheReadTokens": 0, "cacheWriteTokens": 0, "costUsd": 0, "inputTokens": 0, "outputTokens": 0, "reasoningTokens": 0, "steps": 0, "totalTokens": 0, "credits": 0 } } ``` ## Stream worker updates `client.workers.streamUpdates(stringworkerID, RequestOptionsoptions?): WorkerStreamUpdatesResponse | Stream` **get** `/api/workers/{workerId}/stream` Subscribe to a worker using server-sent events. ### Parameters - `workerID: string` ### Returns - `WorkerStreamUpdatesResponse = string` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const response = await client.workers.streamUpdates('t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM'); console.log(response); ``` ## Retrieve a worker email address `client.workers.retrieveEmail(stringworkerID, RequestOptionsoptions?): WorkerRetrieveEmailResponse` **get** `/api/workers/{workerId}/email` Retrieve the inbound email address for a worker. ### Parameters - `workerID: string` ### Returns - `WorkerRetrieveEmailResponse = string` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const response = await client.workers.retrieveEmail('t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM'); console.log(response); ``` #### Response ```json "string" ``` ## Retrieve a worker file `client.workers.retrieveFile(stringfilePath, WorkerRetrieveFileParamsparams, RequestOptionsoptions?): Response` **get** `/api/workers/{workerId}/files/{filePath}` Retrieve a file published from a worker workspace. The runtime route accepts nested paths after /files/. ### Parameters - `filePath: string` - `params: WorkerRetrieveFileParams` - `workerId: string` Worker id returned by the create worker endpoint. ### Returns - `unnamed_schema_2 = Response` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const response = await client.workers.retrieveFile('scratchpad/plan.md', { workerId: 't_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM', }); console.log(response); const content = await response.blob(); console.log(content); ``` ## Domain Types ### Create Worker - `CreateWorker` - `input: string` - `budget?: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `stream?: boolean` ### Worker - `Worker` - `id: string` - `created_at: number | null` - `error: unknown` - `files: Array` - `filename: string | null` - `mediaType: string` - `url: string` - `incomplete_details: unknown` - `messages: Array` - `metadata: Record` - `object: "worker"` - `"worker"` - `output: Array` - `id: string` - `content: Array` - `text: string` - `type: "output_text"` - `"output_text"` - `role: "assistant"` - `"assistant"` - `status: "completed"` - `"completed"` - `type: "message"` - `"message"` - `output_text: string` - `running: boolean` - `sources: Array` - `id: string` - `title: string | null` - `type: "url"` - `"url"` - `url: string` - `status: "running" | "completed" | "pending"` - `"running"` - `"completed"` - `"pending"` - `costs?: Costs | null` - `internalCostUsd: number` - `modelCostUsd: number` - `sandboxCostUsd: number` - `toolCostUsd: number` - `usage?: Usage` - `cacheReadTokens: number` - `cacheWriteTokens: number` - `costUsd: number` - `inputTokens: number` - `outputTokens: number` - `reasoningTokens: number` - `steps: number` - `totalTokens: number` - `credits?: number` ### Worker Stream Updates Response - `WorkerStreamUpdatesResponse = string` ### Worker Retrieve Email Response - `WorkerRetrieveEmailResponse = string` # Schedules ## List worker schedules `client.workers.schedules.list(stringworkerID, RequestOptionsoptions?): ScheduleListResponse` **get** `/api/workers/{workerId}/schedules` List scheduled tasks for a worker. ### Parameters - `workerID: string` ### Returns - `ScheduleListResponse` - `schedules: Array` - `ScheduledWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `nextRunAt: string` - `type: "scheduled"` - `"scheduled"` - `DelayedWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delayInSeconds: number` - `input: string` - `nextRunAt: string` - `type: "delayed"` - `"delayed"` - `CronWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: string` - `input: string` - `nextRunAt: string` - `type: "cron"` - `"cron"` - `IntervalWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `intervalSeconds: number` - `nextRunAt: string` - `type: "interval"` - `"interval"` - `workerId: string` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const schedules = await client.workers.schedules.list('t_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM'); console.log(schedules.schedules); ``` #### Response ```json { "schedules": [ { "id": "id", "budget": "low", "input": "input", "nextRunAt": "2019-12-27T18:11:19.117Z", "type": "scheduled" } ], "workerId": "workerId" } ``` ## Create a worker schedule `client.workers.schedules.create(stringworkerID, ScheduleCreateParamsbody, RequestOptionsoptions?): WorkerSchedule` **post** `/api/workers/{workerId}/schedules` Schedule a worker instruction for a future or recurring run. ### Parameters - `workerID: string` - `body: ScheduleCreateParams` - `input: string` - `when: ScheduledWhen | DelayedWhen | CronWhen | IntervalWhen` - `ScheduledWhen` - `date: string` - `type: "scheduled"` - `"scheduled"` - `DelayedWhen` - `delayInSeconds: number` - `type: "delayed"` - `"delayed"` - `CronWhen` - `cron: string` - `type: "cron"` - `"cron"` - `IntervalWhen` - `intervalSeconds: number` - `type: "interval"` - `"interval"` - `budget?: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` ### Returns - `WorkerSchedule = ScheduledWorkerSchedule | DelayedWorkerSchedule | CronWorkerSchedule | IntervalWorkerSchedule` - `ScheduledWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `nextRunAt: string` - `type: "scheduled"` - `"scheduled"` - `DelayedWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delayInSeconds: number` - `input: string` - `nextRunAt: string` - `type: "delayed"` - `"delayed"` - `CronWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: string` - `input: string` - `nextRunAt: string` - `type: "cron"` - `"cron"` - `IntervalWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `intervalSeconds: number` - `nextRunAt: string` - `type: "interval"` - `"interval"` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const workerSchedule = await client.workers.schedules.create( 't_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM', { input: 'x', when: { date: '2019-12-27T18:11:19.117Z', type: 'scheduled' }, }, ); console.log(workerSchedule); ``` #### Response ```json { "id": "id", "budget": "low", "input": "input", "nextRunAt": "2019-12-27T18:11:19.117Z", "type": "scheduled" } ``` ## Cancel a worker schedule `client.workers.schedules.cancel(stringscheduleID, ScheduleCancelParamsparams, RequestOptionsoptions?): ScheduleCancelResponse` **delete** `/api/workers/{workerId}/schedules/{scheduleId}` Cancel a scheduled task for a worker. ### Parameters - `scheduleID: string` - `params: ScheduleCancelParams` - `workerId: string` Worker id returned by the create worker endpoint. ### Returns - `ScheduleCancelResponse` - `cancelled: boolean` ### Example ```typescript import Handinger from 'handinger'; const client = new Handinger({ apiKey: process.env['HANDINGER_API_KEY'], // This is the default and can be omitted }); const response = await client.workers.schedules.cancel('sch_01HZY31W2SZJ8MJ2FQTR3M1K9D', { workerId: 't_org_123_w_01HZY2ZJQ8G7K42W2D7WF6V4GM', }); console.log(response.cancelled); ``` #### Response ```json { "cancelled": true } ``` ## Domain Types ### Worker Schedule - `WorkerSchedule = ScheduledWorkerSchedule | DelayedWorkerSchedule | CronWorkerSchedule | IntervalWorkerSchedule` - `ScheduledWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `nextRunAt: string` - `type: "scheduled"` - `"scheduled"` - `DelayedWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delayInSeconds: number` - `input: string` - `nextRunAt: string` - `type: "delayed"` - `"delayed"` - `CronWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: string` - `input: string` - `nextRunAt: string` - `type: "cron"` - `"cron"` - `IntervalWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `intervalSeconds: number` - `nextRunAt: string` - `type: "interval"` - `"interval"` ### Schedule List Response - `ScheduleListResponse` - `schedules: Array` - `ScheduledWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `nextRunAt: string` - `type: "scheduled"` - `"scheduled"` - `DelayedWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `delayInSeconds: number` - `input: string` - `nextRunAt: string` - `type: "delayed"` - `"delayed"` - `CronWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `cron: string` - `input: string` - `nextRunAt: string` - `type: "cron"` - `"cron"` - `IntervalWorkerSchedule` - `id: string` - `budget: "low" | "standard" | "high" | "unlimited"` - `"low"` - `"standard"` - `"high"` - `"unlimited"` - `input: string` - `intervalSeconds: number` - `nextRunAt: string` - `type: "interval"` - `"interval"` - `workerId: string` ### Schedule Cancel Response - `ScheduleCancelResponse` - `cancelled: boolean`