Workers API Documentation

Introduction

GrupaAI gives developers durable digital humanoid workers as cloud infrastructure. A worker can operate websites, portals, SaaS apps, credentials, cards, files, tools, and budgets to complete real work.

Use workers.run for on-demand work, workers.create for long-lived workers, and worker.mode to choose one worker, a persistent worker, or a team. Use worker.availability for on-demand, part-time, full-time, or 24/7. The primitive is simple: worker + work + resources + guardrails -> outcome.

work maps to how businesses assign people today — not a single browser step:

• Job ticket — one case or order (prior auth #4412, customer order #9921)
• Shift assignment — one account or queue for a block of time (BPO night shift, Monday RevOps reconcile)
• Function brief — a team objective for a period (grow marketplace liquidity this week)

Installation

The REST API requires no SDK. Use any HTTP client against the base URL supplied with your access. The generated staging reference uses https://api.staging.grupa.ai.

For approved SDK users:

Authentication

Every API request uses HTTP Bearer authentication. Keep keys server-side and load them from an environment variable.

In Swagger Docs, select Authorize and paste the key without a Bearer prefix; the console adds it. Approved SDK users can initialize the client as follows:

Quick Start

Start a durable worker run with a single REST request. The API accepts the run and returns 202 Accepted with a WorkerRun.

Private-beta SDK equivalent

If your account includes SDK access, the equivalent call is:

Work Runs

A Work Run is one assignment given to one worker or a team of workers — the same unit a manager would assign to a person: a job ticket, shift assignment, or function brief. Every run has an outcome contract, status, trace, metadata, resources, and optional guardrails.

• worker - role, topology mode, and availability.
• work - required. Natural-language description of the job to complete.
• resources - optional. Credentials, card, files, tools, budget, and context.
• guardrails - optional. Approvals, spend limits, submit gates, and timeouts.
• outcome - optional. What should be returned when the work is finished.
• output - optional. Recording, structured deliverable contract, and PII masking controls.
• scheduleAt - optional. Future dispatch time, up to 365 days ahead.
• idempotencyKey - optional SDK field mapped to the Idempotency-Key header.
• webhook - optional. URL for worker lifecycle events.
• metadata - optional. Your IDs for correlation.

Run statuses are pending, running, needs_approval, stuck, verifying, completed, failed, and canceled.

Workers

Workers are the core primitive. Choose how they are deployed with worker.mode, then choose when they run with worker.availability.

• mode: "single" - one worker, one outcome.
• mode: "persistent" - long-lived worker for repeat assignments.
• mode: "team" or "auto" - run multiple roles or let GrupaAI choose topology.
• availability: "on_demand" - spin up for one job, then done.
• availability: "part_time" - scheduled repeat work for specific windows.
• availability: "full_time" - active through business hours for a function.
• availability: "24_7" - always-on worker for autonomous operations.

Resources

Resources are what the worker can use: portal logins, payment methods, files, built-in tools, MCP servers, custom APIs, budgets, and scoped secrets. Reference credential IDs, zero-custody connection IDs, agent identities, card IDs, and uploaded file IDs instead of embedding raw secrets or file contents in a run.

Files

Upload immutable CSV, XLS/XLSX, or binary inputs up to 25 MiB using POST /v1/files and the required X-GrupaAI-File-Name header. The returned opaque file_... ID is safe to place in resources.files.

Credentials

POST /v1/credentials stores encrypted login, API-token, OAuth, or HTTP-header material and returns metadata without secret values. For zero-custody access, use credential broker manifests and credential connections; runs receive only ready connection IDs or an independently brokered agentIdentity.

Webhooks & Lifecycle

Register an HTTPS webhook URL on a run or create an account-level subscription with POST /v1/webhook-subscriptions. Run submission returns webhookSigningSecret only when a per-run webhook is configured. Store it immediately.

• worker.started - worker began execution
• worker.needs_approval - paused for a human gate (payments, submits)
• worker.verifying - outcome produced; running the independent check
• worker.stuck - no progress / blocked (e.g. rate-limited); the worker paused and reported instead of looping
• worker.completed - success with outcome, cost, verification, and trace URL
• worker.failed - terminal failure with error detail

Every delivery is signed. Verify the X-Grupa-Signature header before trusting a payload (see Production Essentials → Webhook Signing), and treat unsigned requests as hostile.

Auto Topology

If you prefer not to design worker topology, use worker.mode: "auto" on workers.run. The platform decides worker count, team roles, and sequencing from your goal.

Worker Teams & Visibility

When you run a team, GrupaAI provisions specialized workers for the work: researchers, operators, reviewers, schedulers, or custom roles you define.

Full Visibility: Unlike black-box solutions, GrupaAI provides a real-time trace of the entire worker team's activity. The onUpdate callback receives events from all workers, allowing you to show the user exactly what is happening.

Tools & Integration

Attach tools inside resources: built-in tools, MCP servers, or custom API endpoints.

Built-in Tools

These tools are always available. Pass them in resources.tools:

• web_search - Search the web for information
• email_send - Send emails with custom content
• calendar_invite - Create and manage calendar events
• file_upload - Upload and process files
• code_execution - Execute code in secure environments

MCP (Model Context Protocol) Servers

Connect standard data sources with simple connection strings:

Custom Tools

Connect your internal APIs and proprietary systems:

Approvals

Gate high-stakes actions - payments, form submits, message sends - with human-in-the-loop approval. Works on any worker mode.

Budget & Controls

Budgets and limits are the outer guardrail — but a worker also stops on its own judgment. Like a competent person, it continuously checks whether it is actually making progress. If it hits a wall (a rate limit, a dead control, repeated no-op actions), it does not loop or invent busywork: it enters stuck, emits a worker.stuck event explaining what blocked it, and waits for input instead of burning budget. Attach budget and guardrails.timeout as the hard backstop under that judgment.

• resources.budget: Maximum spend in USD for the worker run.
• guardrails.timeout: Maximum duration in milliseconds.
• guardrails.approvals: Actions that must pause for human approval.

REST Endpoint Reference

This catalog mirrors the current OpenAPI 1.0.0 staging contract. The Swagger Docs remains canonical for request bodies, responses, limits, and newly promoted endpoints.

Private-beta SDK Reference

Convenience methods for accounts that have been granted access to @grupaai/sdk. The REST/OpenAPI contract above is canonical.

workers.run(config)

Start one on-demand worker or a worker team. Returns a run object with id, status, and eventually an outcome.

Parameters

Returns

workers.create(config)

Create a persistent worker that can receive repeated assignments. Use this for BPO operations, recurring admin work, and long-lived worker identities. Calling workers.run with worker.mode: "persistent" is shorthand that auto-creates a worker and assigns the run to it; use create() + assign() when you need to reuse one worker identity across many assignments.

Persistent Worker Parameters

Returns

Type Definitions

Selected convenience types used by the private-beta SDK examples. The generated OpenAPI schemas are canonical and include complete validation constraints.

Run & worker methods

• client.workers.retrieveRun(runId) - fetch one run by id
• client.workers.listRuns() - paginated list of runs (limit, cursor params)
• client.workers.cancel(runId) - stop an in-flight run
• client.workers.pause(workerId) / .resume(workerId) / .delete(workerId) - manage a persistent worker (this is how a worker reaches the "paused" status)

Verification & Proof

Every run returns evidence, not just an answer. Alongside outcome, a completed run returns cost (actual spend), a trace with screenshot proof of each step, and an independent verification result checked against the outcome criteria you set.

• verification.status: "passed" - an independent check confirmed the outcome against your criteria.
• "failed" - the check found the outcome does not meet the criteria. The run is flagged, never silently returned as done.
• "unverified" - the outcome could not be confirmed yet (e.g. a source is pending). The run stays in verifying and re-checks on a schedule until it can close or escalate.

Pass outcome as an object to set structured, checkable criteria. The screenshot trace and verification checks are retained as an audit trail for regulated workflows. Screenshots are the default proof; set output.recording = true to also get a full video replay when a person needs to watch the run back — a reviewer verifying, or a learner rewatching a session.

Use output.contract when the worker must produce validated JSON, CSV, or XLSX deliverables. Set output.piiMasking = true to de-identify screenshot proof and trace payloads before persistence. Recordings are not masked and can have independent retention.

Use the run and per-agent artifact endpoints to list and download immutable screenshots, recordings, and output files. Each artifact includes its MIME type, size, SHA-256 digest, creation time, and retention deadline.

Collaboration — Pair & Teach

A worker is not limited to solo autonomous work. Like a person, it can share an environment with a human — watch what they do, demonstrate a step, let them try, and coach as they go. These are innate abilities, not a separate mode: the worker decides whento work alone, pair, or teach from the work and role you give it, exactly as a colleague would.

• Watch - perceives the human's live actions on the shared screen, not just the page.
• Demonstrate - performs a step to show how, then holds.
• Observe & stay present - keeps watching while the human attempts it. This is continuous co-presence, never a blind pause.
• Coach - gives feedback or corrects, without seizing control.

You never set a "teaching mode." Assign work like "Train the new analyst to run month-end reconciliation" or "Pair with me on this filing", and the worker chooses co-presence on its own. The trace records demonstrated, watching, human_acted, and coached events, so the session stays fully auditable and replayable.

• GET /v1/runs/{runId}/live-preview - stream a read-only worker desktop.
• POST /v1/runs/{runId}/collaboration - create a single-use, short-lived shared-screen link.
• GET /v1/runs/{runId}/agents - list addressable workers in a team run.
• GET /v1/runs/{runId}/agents/{agentId}/live-preview - preview one worker.
• POST /v1/runs/{runId}/agents/{agentId}/collaboration - collaborate with one worker.

Memory & Learning

Set memory.enabled on a worker to let it remember across assignments. Memory works at three levels, like a person's:

• Working memory - within a single run, the worker carries context across every step; the trace is its record.
• Long-term memory - a persistent worker retains what it learned across assignments (how a portal is laid out, where a control lives, what failed last time), so repeat work gets faster and more reliable.
• Learning from coaching - in a Pair & Teach session, when a human corrects or demonstrates, that feedback is retained and applied to later work. The worker improves from being taught, not only from doing.

Memory is per-worker and tenant-isolated. You can inspect and clear it, and nothing persists unless you enable it — off by default. Use GET /v1/workers/{workerId}/memory to inspect the current version and DELETE /v1/workers/{workerId}/memory to clear it immediately.

Production Essentials

Everything you need before pointing real, money-moving, form-submitting traffic at a worker.

Idempotency

Send an 8-200 character Idempotency-Key header when creating runs or financial operations. The SDK's idempotencyKey field maps to that header. An exact retry returns the original operation; reusing a key with different inputs returns 409 Conflict.

Errors & Status Codes

Errors return a non-2xx HTTP status and a typed body with an errorobject carrying code (an ErrorCode), message, and requestId.

• 400 invalid request · 401 authentication failure · 402 budget or billing failure · 403 forbidden · 404 not found · 409 conflicting state or mismatched idempotency reuse · 422 invalid configuration · 429 rate limited · 503 temporarily unavailable

Rate Limits

Over the limit returns 429 with a Retry-After header and X-RateLimit-Remaining / X-RateLimit-Reset. Back off and retry; the SDK does this automatically with jitter. Per-plan quotas are on your dashboard.

Cancellation

POST /v1/runs/{runId}/cancel durably requests cancellation and returns 202; an already terminal run returns 200. A canceled run settles to status = "canceled". Persistent workers use pause, resume, and delete.

Environments & Versioning

The API is versioned in the base path. The Swagger reference currently targets https://api.staging.grupa.ai/v1; use the production base URL supplied with production access. Breaking changes ship under a new version. Keys prefixed grupa_test_ run in a sandbox that simulates external submits and payments — no real money moves and no real forms are filed — so you can integrate safely. Override the host by passing a baseURL option to the client.

Webhook Signing

Every webhook POST includes an X-Grupa-Signature header: an HMAC-SHA256 of the raw request body using your webhook secret. Recompute it and compare in constant time before trusting the payload; reject anything that doesn't match or is unsigned. This is what prevents a spoofed worker.completed or a forged payment approval.

Testing & Development

Test worker instructions, resources, guardrails, and expected outcomes before running in production.

Dry Run Mode

Plan and validate worker steps without executing actual external actions.

Validation Mode

Validate worker configuration and connected tools without running the full workflow.

Error Handling & Recovery

Build robust worker runs with comprehensive error handling and recovery strategies.

Mid-flight Intervention

Pause and intervene when workers need human guidance, approval, or updated instructions.

Error Recovery Strategies

Configure how workers handle failures and retry logic.

Security & Compliance

Enterprise-grade security with credential management and audit trails.

Credential Vault

Portal logins and payment methods live in the credentials vault. Reference vault IDs in worker runs — never embed raw secrets in source code. Secrets are encrypted at rest with per-tenant keys and injected only at the browser/execution layer at the moment of use: the reasoning model never receives raw credential values, and they are redacted from traces, screenshots, and logs.

Data Handling & Retention

Traces, screenshots, and recordings can contain PII/PHI by construction — a portal screen holds real data. Artifacts are encrypted at rest, access-controlled per tenant, and returned with an explicit retentionUntil. DELETE /v1/data-retention/runs/{runId} cancels a live run and permanently deletes its parent/child data. Set output.piiMasking = true to de-identify screenshot proof and trace payloads before persistence. Keep work and outcome free of unnecessary PII — treat them as logged.

Deployment & Isolation

Workers run in isolated, per-run sandboxes with tenant data separation; browser state, cookies, and cache are wiped between assignments. Single-tenant and customer-VPC deployment (with egress allowlisting) are available for regulated buyers. Approvals are enforced and recorded server-side for non-repudiation — not trusted from the client callback alone.

Access & Keys

• Scoped keys: create keys with runs:read, runs:write, keys:manage, audit:read, vaults:use, vaults:manage, or admin.
• Sandbox: creating a key with sandbox: true returns a grupa_test_ key that suppresses consequential external actions.
• Rotation: use POST /v1/api-keys/{keyId}/rotate; raw key material is returned only when created or rotated.
• Audit: GET /v1/audit-events exports immutable credential, approval, memory, and key events.

Compliance

SOC 2 and a DPA (with subprocessor list and data-residency options) are available under NDA; a BAA is available for HIPAA-covered workflows. Because workers operate consumer-data portals, FCRA roles and permissible-purpose are addressed in your agreement. Contact us for current reports and terms — we do not represent certifications we do not hold.

Examples

Each example is real work companies assign today — job tickets and shift assignments you wire into your product, plus function briefs for worker teams.

Replace ops workflows

Plug these into your app or ops stack. One API call maps to one assignment a coordinator would hand to a human today.

Job ticketOn-demand portal worker

Human parallel: RCM coordinator assigns case #4412 to a portal specialist for prior auth submission.

Shift assignmentPersistent BPO worker

Human parallel: BPO supervisor assigns overnight vendor portal queue clearing for one client account.

Shift assignmentEnterprise ops worker

Human parallel: RevOps lead assigns the Monday standup reconcile across Salesforce, HubSpot, billing, and recruiting.

Job ticketPayment with approval

Human parallel: Commerce ops fulfills wholesale order #7721 in checkout with manager approval before payment.

Run a business function

Delegate objectives teams already own. Use mode: "team" or persistent workers; GrupaAI decomposes the brief into sub-work until the outcome is met.

Function briefMarketplace worker team

Human parallel: Marketplace ops lead assigns the team — grow supply, demand, and matches this week.

Function briefMarketplace matching team

Human parallel: Ops assigns matchers to pair supply listings with buyer requests for the week.

Function briefAdvanced: automatic worker topology

Human parallel: Partner assigns analyst — find and diligence pre-seed AI infra startups this month.

Use worker.mode: "auto" when you want GrupaAI to choose whether the brief needs one worker or a team.

Use Cases

Businesses and product categories that become easier to build with autonomous workers as execution infrastructure.

Billing

GrupaAI costs less than building worker infrastructure — and less than hiring humans to do the same work. You are billed based on:

• Worker active time: Pay for workers while they are running work.
• Availability: On-demand, part-time, full-time, and 24/7 workers can be priced by usage and volume.
• Infrastructure included: Cloud runtime, browser sessions, model routing, traces, approvals, and worker orchestration.
• Resources separate: External spend controlled by resources.budget, card limits, and approval guardrails.

A run's cost.status is pending, partial, or reported. Retrieve invoice-backed source line items and totals from GET /v1/runs/{runId}/cost-breakdown. The response separates gross cost, credits, direct and shared cloud costs, external providers, and descendant-run costs.

GET /v1/billing returns the authoritative tenant billing account. Billing mandates, setup intents, saved payment methods, and balance payments are available through the billing endpoints in the REST catalog above.

Build autonomous businesses on GrupaAI like you build on payments or compute — call the API, attach resources, get outcomes back.