> ## 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. # List tasks > Cancelled jobs, and jobs under deleted Workers, are both excluded. `?workerId=` narrows to one Worker; a malformed id there is a 400, while a well-formed one naming another organization's Worker answers an empty list. ## OpenAPI ````yaml /openapi.json get /api/v1/tasks 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/tasks: get: tags: - tasks summary: List tasks description: >- Cancelled jobs, and jobs under deleted Workers, are both excluded. `?workerId=` narrows to one Worker; a malformed id there is a 400, while a well-formed one naming another organization's Worker answers an empty list. operationId: listTasks parameters: - name: workerId in: query required: false description: >- Narrow to one Worker. A malformed id is a 400; a well-formed id naming another organization's Worker answers an empty list. schema: type: string description: >- Narrow to one Worker. A malformed id is a 400; a well-formed id naming another organization's Worker answers an empty list. - name: clientId in: query required: false description: >- Narrow to one Client. Rows that belong to no Client — a core-tier ework, a room marked internal, a core-tier task — are excluded, because they are not that Client's. A malformed id is a 400; a well-formed id naming another organization's Client answers an empty list. schema: type: string description: >- Narrow to one Client. Rows that belong to no Client — a core-tier ework, a room marked internal, a core-tier task — are excluded, because they are not that Client's. A malformed id is a 400; a well-formed id naming another organization's Client answers an empty list. - name: limit in: query required: false description: >- Page size. Defaults to 50, clamped at 200. A value that is not a positive integer is a 400. schema: type: integer description: >- Page size. Defaults to 50, clamped at 200. A value that is not a positive integer is a 400. - name: cursor in: query required: false description: >- Opaque keyset cursor from the previous page's `page.nextCursor`. A cursor this API did not issue is a 400, never a silent page one. schema: type: string description: >- Opaque keyset cursor from the previous page's `page.nextCursor`. A cursor this API did not issue is a 400, never a silent page one. responses: '200': description: Success. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Task' description: The page. page: $ref: '#/components/schemas/PageInfo' required: - data - page additionalProperties: false example: data: - id: 5d6e7f80-91a2-4b3c-8d4e-5f60718293a4 organizationId: 0d4c9f2e-4b8a-4a5b-9e21-6f9c2a1b7d30 workerId: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f clientId: c1a2b3c4-d5e6-4f70-8912-3a4b5c6d7e8f workClientId: c1a2b3c4-d5e6-4f70-8912-3a4b5c6d7e8f tier: client title: Morning support digest prompt: >- Summarise anything still open in this channel from the last 24 hours. schedule: kind: cron runAt: null cronExpr: 0 8 * * 1-5 timezone: Europe/London status: scheduled state: scheduled closedOutcome: null dueAt: null late: false requester: kind: person workerId: null slackUserId: U0A1B2C3D4F clerkUserId: null teamId: null openRoleId: null holder: kind: worker workerId: 8f1c2d3e-9a4b-4c5d-8e6f-1a2b3c4d5e6f slackUserId: null clerkUserId: null teamId: null openRoleId: null enabled: true silent: false targetChannel: null origin: channel: C0A1B2C3D4E channelType: channel threadTs: '1772620000.000100' slackUserId: U0A1B2C3D4F lastRunAt: '2026-03-04T08:00:04.000Z' nextRunAt: '2026-03-05T08:00:00.000Z' createdBy: agent createdByEworkId: 3b7e1c44-2d59-4f0a-9c81-5e6d7a8b9c01 createdAt: '2026-02-20T09:31:12.000Z' updatedAt: '2026-03-04T08:00:09.000Z' page: limit: 50 hasMore: true nextCursor: >- MjAyNi0wMy0wNFQwOToxNDowMi4wMDBafDhmMWMyZDNlLTlhNGItNGM1ZC04ZTZmLTFhMmIzYzRkNWU2Zg '400': description: '`invalid_request`' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '`unauthorized`' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`rate_limited`' content: application/json: schema: $ref: '#/components/schemas/Error' security: - orgApiKey: - tasks:read components: schemas: Task: type: object description: >- One task — a scheduled job is a task whose start repeats or is set for later. properties: id: type: string description: The task id. organizationId: type: string description: Always your own organization. workerId: type: string description: The Worker that runs it. clientId: type: - string - 'null' description: >- The Client the task's scope is bound to: who owns the row. Null on a core-tier task. Where its runs execute is `workClientId`. workClientId: type: - string - 'null' description: >- Null when its targets name no client, or more than one; each run is then its own target's client's work. Otherwise the Client whose work this task is: a client-tier task's own client, or the one client its targets name. Its runs execute on that client's agent. tier: type: string enum: - core - client description: >- The tier of the task's scope, beside `clientId`. A core-tier task whose targets name a client still runs on that client's agent; see `workClientId`. title: type: string description: What the job is called. prompt: type: string description: The text the agent is given when it fires. schedule: type: object description: When the job fires. properties: kind: type: string enum: - once - cron description: A one-off instant, or a repeating expression. runAt: type: - string - 'null' format: date-time description: The instant a `once` job fires. cronExpr: type: - string - 'null' description: The five-field cron expression a `cron` job fires on. timezone: type: - string - 'null' description: IANA zone the expression is read in. required: - kind - runAt - cronExpr - timezone additionalProperties: false status: type: string description: >- The task's status in a word: `scheduled`, `in progress`, or — once closed — how it ended: `resolved`, `archived`, `declined` or `cancelled`. The same fact as `state` and `closedOutcome`, read together. state: type: string enum: - scheduled - in_progress - closed description: >- `scheduled` — assigned, not started (a recurring job waiting for its next run included). `in_progress` — work has started. `closed` — done; a closed task never fires. closedOutcome: type: - string - 'null' description: >- How a closed task ended — `resolved`, `archived`, `declined` or `cancelled`. Null on an open one. `declined` is a person saying no, not a failed run. dueAt: type: - string - 'null' format: date-time description: >- When the task is expected done. Context only: nothing fires when it passes. late: type: boolean description: >- Past `dueAt` and not closed, as of this read. Computed, never stored. requester: type: - object - 'null' description: >- Who asked for it. Null when nobody did — a task opened by an API key, or by the platform. properties: kind: type: string enum: - worker - person - team - role description: >- What kind of party this is. Every id below that is not of this kind is null. workerId: type: - string - 'null' description: The Worker, when `kind` is `worker`. slackUserId: type: - string - 'null' description: >- The person's Slack user id, when `kind` is `person` and it is known. clerkUserId: type: - string - 'null' description: >- The person's user id in this app, when `kind` is `person` and it is known. teamId: type: - string - 'null' description: The team, when `kind` is `team`. openRoleId: type: - string - 'null' description: The open role, when `kind` is `role`. required: - kind - workerId - slackUserId - clerkUserId - teamId - openRoleId additionalProperties: false holder: type: object description: Who holds it now — who the work is with. properties: kind: type: string enum: - worker - person - team - role description: >- What kind of party this is. Every id below that is not of this kind is null. workerId: type: - string - 'null' description: The Worker, when `kind` is `worker`. slackUserId: type: - string - 'null' description: >- The person's Slack user id, when `kind` is `person` and it is known. clerkUserId: type: - string - 'null' description: >- The person's user id in this app, when `kind` is `person` and it is known. teamId: type: - string - 'null' description: The team, when `kind` is `team`. openRoleId: type: - string - 'null' description: The open role, when `kind` is `role`. required: - kind - workerId - slackUserId - clerkUserId - teamId - openRoleId additionalProperties: false enabled: type: boolean description: False means it is parked and fires nothing. silent: type: boolean description: True when the fire deliberately posts nothing. targetChannel: type: - string - 'null' description: >- Where the run posts, when it is not the channel it was scheduled from. origin: type: object description: Where the job came from. properties: channel: type: - string - 'null' description: The channel it was scheduled from. channelType: type: - string - 'null' description: '`channel` | `group` | `im` | `mpim`.' threadTs: type: - string - 'null' description: The thread it was scheduled in. slackUserId: type: - string - 'null' description: Who scheduled it, when a person did. required: - channel - channelType - threadTs - slackUserId additionalProperties: false lastRunAt: type: - string - 'null' format: date-time description: When it last ran, for any of its clients. Null if it never has. nextRunAt: type: - string - 'null' format: date-time description: >- When it runs next: the soonest any enabled client is due. Null when none is scheduled. createdBy: type: string enum: - operator - agent - system description: >- Who created it: a person (`operator`), a worker (`agent`), or the platform itself (`system`). createdByEworkId: type: - string - 'null' description: The ework that created it, when an agent did. createdAt: type: string format: date-time description: When the job was created. updatedAt: type: string format: date-time description: When it last changed. required: - id - organizationId - workerId - clientId - workClientId - tier - title - prompt - schedule - status - state - closedOutcome - dueAt - late - requester - holder - enabled - silent - targetChannel - origin - lastRunAt - nextRunAt - createdBy - createdByEworkId - createdAt - updatedAt additionalProperties: false PageInfo: type: object description: Present on every list, even when there is nothing more to fetch. properties: limit: type: integer description: The page size actually applied, after clamping. hasMore: type: boolean description: True when another page exists. nextCursor: type: - string - 'null' description: >- Feed back as `?cursor=`. Null when `hasMore` is false — and always null on a list that takes no `cursor` parameter, which ranks its rows rather than paging them and says so on its own page. Narrow that list's `query` instead. required: - limit - hasMore - nextCursor 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.