> ## Documentation Index > Fetch the complete documentation index at: https://docs.ergoly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a worker > Carries `latestProvisioningJob` — the current step, and the error text of a failure — so a stuck Worker can be diagnosed in one call. Null when the Worker has never been provisioned. It is always the CURRENT run, which is why this is the call to poll after a Slack install: that install starts a fresh run rather than resuming the one that was waiting. `installUrl` mirrors the run's, so one call answers whether an install is still owed as well. It also carries the worker's two role lists, `responsibilities` and `behaviors`, as Markdown — read from the worker's own memory, null until it has been provisioned, and not editable through this resource. ## OpenAPI ````yaml /openapi.json get /api/v1/workers/{id} openapi: 3.1.0 info: title: Ergoly platform API version: 1.0.0 description: >- Read and change one organization's own Ergoly environment. Every route is scoped to the organization the presented credential resolves to; there is no parameter that widens it. The human-readable reference is served from the same namespace at `/api/v1/docs`, behind the same credential. The namespace's front door is `GET /api/v1`, and it is deliberately absent from `paths` below. It answers without a credential — what this API is, how an organization admin mints a key, and where the reference lives — so it is the way in to this contract rather than a part of it: it has no scope, takes no parameters, and there is nothing about it for a generated client to call. Every `unauthorized` refusal carries that same URL as `error.docs`. servers: - url: https://control.ergoly.ai security: - orgApiKey: [] tags: - name: auth description: How to present a key, what it is scoped to, and what a 401 means. - name: organization description: Which organization your credential resolves to. - name: workers description: The Slack apps and bot identities in your organization. - name: eworks description: The runtime instances under a Worker — one core, one per bound Client. - name: clients description: The customers a Worker can be scoped to, and how to bind one. - name: channels description: Which Slack rooms a Worker answers in, and who it answers as. - name: tasks description: >- Tasks handed between Workers and people, scheduled jobs, their targets, and their run history. - name: jobs description: How a provisioning run is going — the other half of every 202. - name: memory description: Read and write the memory tiers an ework mounts. - name: connections description: The credentials your agents use, and the hosts they are injected on. - name: webhooks description: Inbound URLs an outside system can POST to, each of which starts a turn. - name: activity description: Your organization's audit feed. - name: usage description: Cost, turn outcomes and a per-day pulse over a window you choose. - name: errors description: The closed set of refusal codes, and what to do about each. paths: /api/v1/workers/{id}: get: tags: - workers summary: Get a worker description: >- Carries `latestProvisioningJob` — the current step, and the error text of a failure — so a stuck Worker can be diagnosed in one call. Null when the Worker has never been provisioned. It is always the CURRENT run, which is why this is the call to poll after a Slack install: that install starts a fresh run rather than resuming the one that was waiting. `installUrl` mirrors the run's, so one call answers whether an install is still owed as well. It also carries the worker's two role lists, `responsibilities` and `behaviors`, as Markdown — read from the worker's own memory, null until it has been provisioned, and not editable through this resource. operationId: getWorker parameters: - name: id in: path required: true description: >- The Worker id. A malformed id answers 404, exactly as another organization's well-formed id does. schema: type: string description: >- The Worker id. A malformed id answers 404, exactly as another organization's well-formed id does. responses: '200': description: Success. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WorkerDetail' required: - data additionalProperties: false example: data: id: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f organizationId: 0d4c9f2e-4b8a-4a5b-9e21-6f9c2a1b7d30 slug: rowan displayName: Rowan description: Answers support questions in the shared customer channels. roleTitle: Support engineer status: active lastError: null quarantined: false quarantineReason: null quarantinedAt: null slack: appId: A0A1B2C3D4E teamId: T0A1B2C3D4E teamName: Northwind botUserId: U0A1B2C3D4E installedScopes: app_mentions:read,channels:history,chat:write,files:read eventsUrl: >- https://foreman.ergoly.ai/api/foreman/northwind/rowan/slack/events overrides: thinkingStatusText: null thinkingTimeoutMs: null routingErrorEmoji: null createdAt: '2026-02-11T14:03:22.000Z' updatedAt: '2026-03-04T09:14:02.000Z' latestProvisioningJob: id: 2f3e4d5c-6b7a-4980-8172-63544536271f status: succeeded currentStep: mark_active error: null installUrl: null startedAt: '2026-03-04T09:12:41.000Z' completedAt: '2026-03-04T09:19:07.000Z' createdAt: '2026-03-04T09:12:38.000Z' installUrl: null responsibilities: > # My responsibilities - Answer support questions in the shared customer channels - Escalate a refund request to a person rather than promising one ## Changes 2026-03-04 — added refunds because the support lead asked in #support-ops behaviors: | # My behaviors - Prefer a short answer with a link over a long one without - Don't quote another customer's ticket, even anonymised ## Changes '401': description: '`unauthorized`' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '`not_found`' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`rate_limited`' content: application/json: schema: $ref: '#/components/schemas/Error' security: - orgApiKey: - workers:read components: schemas: WorkerDetail: type: object description: >- One Worker, with its latest provisioning attempt and its two role lists attached. properties: id: type: string description: The Worker id — the `{id}` every Worker-addressed route takes. organizationId: type: string description: Always your own organization. slug: type: string description: URL-safe name, unique within the organization. displayName: type: string description: The name the agent answers to in Slack. description: type: - string - 'null' description: What this Worker is for. roleTitle: type: - string - 'null' description: The role the agent presents as. status: type: string description: >- Provisioning lifecycle: `awaiting_install` | `provisioning` | `active` | `failed`. lastError: type: - string - 'null' description: The most recent provisioning failure text. quarantined: type: boolean description: True when the Worker has been pulled out of service. quarantineReason: type: - string - 'null' description: Why it was quarantined. quarantinedAt: type: - string - 'null' format: date-time description: When it was quarantined. slack: type: object description: Slack app identity. No credential of any kind is included here. properties: appId: type: - string - 'null' description: The Slack app id. teamId: type: - string - 'null' description: The workspace the app is installed in. teamName: type: - string - 'null' description: That workspace's name. botUserId: type: - string - 'null' description: The bot's own Slack user id. installedScopes: type: - string - 'null' description: Comma-separated scopes the install actually granted. eventsUrl: type: - string - 'null' description: The events URL Slack posts to. required: - appId - teamId - teamName - botUserId - installedScopes - eventsUrl additionalProperties: false overrides: type: object description: Per-Worker foreman overrides. Null means the fleet default applies. properties: thinkingStatusText: type: - string - 'null' description: Per-Worker shimmer text. Null means the fleet default. thinkingTimeoutMs: type: - integer - 'null' description: Per-Worker thinking timeout. Null means the fleet default. routingErrorEmoji: type: - string - 'null' description: Reaction used when a turn cannot be routed. required: - thinkingStatusText - thinkingTimeoutMs - routingErrorEmoji additionalProperties: false createdAt: type: string format: date-time description: When the Worker was created. updatedAt: type: string format: date-time description: When it last changed. latestProvisioningJob: type: - object - 'null' description: >- The most recent provisioning attempt, or null when the Worker has never been provisioned. properties: id: type: string description: The job id. Poll it at `GET /api/v1/jobs/{id}`. status: type: string description: >- `pending` | `running` | `succeeded` | `failed`. A run WAITING on the Slack install is `pending` at `currentStep: "await_oauth_install"` — `awaiting_install` is the WORKER's status, not a job's. currentStep: type: - string - 'null' description: The step the run is on, or stopped on. error: type: - string - 'null' description: Why the run failed. Null while it is healthy. installUrl: type: - string - 'null' description: >- Where a Slack workspace admin finishes the install. A string only while this run is stopped waiting for one — `currentStep` is `await_oauth_install` and the run has not settled. Null otherwise, including on a run that failed on that step. Open it in a browser as a workspace admin; the run then carries on by itself. startedAt: type: - string - 'null' format: date-time description: When the run began. completedAt: type: - string - 'null' format: date-time description: When it reached a terminal state. createdAt: type: string format: date-time description: When the job row was written. required: - id - status - currentStep - error - installUrl - startedAt - completedAt - createdAt additionalProperties: false installUrl: type: - string - 'null' description: >- The same value as `latestProvisioningJob.installUrl`, lifted here so a caller polling the Worker need not reach into the run. Null whenever no install is being waited on. responsibilities: type: - string - 'null' description: >- The worker's responsibilities list — the high-order things it is trained and proven capable of, and responsible for in its role — as the Markdown body of `always/11-responsibilities.md` in its worker memory tier. Sits beside `description`, the charter's prose. Null until the Worker has been provisioned. Read-only here: the worker edits it from its own sandbox once a person has said yes to the change it proposed, and an operator edits it through the memory endpoints. behaviors: type: - string - 'null' description: >- The worker's behaviors list — what it follows day to day, written as Avoid / Don't / Prefer / Use lines — as the Markdown body of `always/12-behaviors.md` in its worker memory tier. Null until the Worker has been provisioned. Read-only here, on the same terms as `responsibilities`. required: - id - organizationId - slug - displayName - description - roleTitle - status - lastError - quarantined - quarantineReason - quarantinedAt - slack - overrides - createdAt - updatedAt - latestProvisioningJob - installUrl - responsibilities - behaviors additionalProperties: false Error: type: object description: The one error shape. Every refusal in this namespace has it. properties: error: type: object description: The refusal. properties: code: type: string enum: - unauthorized - not_found - invalid_request - conflict - quota_exceeded - rate_limited - upstream_error - gone description: The machine-stable half. Branch on this, never on `message`. message: type: string description: Prose for a human reading a terminal. docs: type: string description: >- Where to learn how to authenticate. Present on `unauthorized` and on nothing else — it is the one refusal a caller can reach with no credential at all, so it is the one that has to say where the way in is. required: - code - message additionalProperties: false required: - error additionalProperties: false securitySchemes: orgApiKey: type: http scheme: bearer description: >- An organization-scoped API key, minted in control under Settings → API keys. Every failure to authenticate answers one identical 401: "Provide a valid organization-scoped API key or an active session." Each operation names the one scope it is filed under, `:`, where the resource is the first path segment after `/api/v1/`; a key minted today carries all 22 of them. Scopes are RECORDED — on the key and on every audit row — and are not yet enforced: no request is refused for want of one. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.