# Ergoly

> How to manage your agency on Ergoly

- [Ergoly](https://docs.ergoly.ai/index.md): AI Workers you own, separated per client, inside the Slack your agency already uses.
- [Core Concepts](https://docs.ergoly.ai/core-concepts.md)
- [A day with a worker](https://docs.ergoly.ai/a-day-with-a-worker.md): One worker, two clients, one morning. What it looks like from inside Slack.
- [Getting started](https://docs.ergoly.ai/getting-started.md): From the invitation to your first worker answering in Slack.
- [Getting access](https://docs.ergoly.ai/getting-started/access.md): Onboarding with the Ergoly team: an invitation to control and a shared channel in Slack.
- [Meet your AI Admin](https://docs.ergoly.ai/getting-started/ai-admin.md): Connect Slack, name it, install it. It messages you and sets up your company and your first worker from there.
- [Add a client and a channel](https://docs.ergoly.ai/getting-started/first-client.md): Tell the AI Admin who the client is, and which Slack channel is theirs. From then on, the worker answers there as your agency.
- [Your first correction](https://docs.ergoly.ai/getting-started/first-correction.md): Say what you want done differently, once. The worker writes it down and files it with the right client, the right worker, or the whole company.
- [Company](https://docs.ergoly.ai/company.md): Your agency on Ergoly: the chart of people and workers, the teams and clients, the settings, and who can do what.
- [Chart](https://docs.ergoly.ai/company/chart.md): An org chart that holds people and workers side by side. Drag to place, and the chart decides who a worker turns to when it needs a person.
- [Members](https://docs.ergoly.ai/company/members.md): People and workers are listed side by side. Who can sign in to control is a separate list.
- [Teams](https://docs.ergoly.ai/company/teams.md): Three kinds of team: your own, a client, and a vendor. Each holds different things.
- [Settings](https://docs.ergoly.ai/company/settings.md): Six tabs: Slack, Members, API keys, Avatars, Email, and Tasks.
- [Access](https://docs.ergoly.ai/company/access.md): Three ways into your company: a person in control, the AI Admin in Slack, and an API key.
- [Workers](https://docs.ergoly.ai/workers.md): An AI member of your company. It has a name, a job, responsibilities and behaviors you set, and a separate copy for each client it serves.
- [Identity](https://docs.ergoly.ai/workers/identity.md): A name, an avatar, a Slack app, and an email address. Change any of them from the worker's Settings tab.
- [Role](https://docs.ergoly.ai/workers/role.md): The job title, and the one-line job it does. A worker is a role, not an automation.
- [Responsibilities](https://docs.ergoly.ai/workers/responsibilities.md): The list of what a worker is trained for and accountable for. Requests outside the list are outside its job.
- [Behaviors](https://docs.ergoly.ai/workers/behaviors.md): What a worker follows day to day, as Avoid, Don't, Prefer and Use lines. Read every turn, changed only by agreement.
- [Response policy](https://docs.ergoly.ai/workers/response-policy.md): When a worker speaks: only when @-mentioned, or to anything it judges is for it. And whether it listens when not addressed.
- [Reporting](https://docs.ergoly.ai/workers/reporting.md): Who a worker reports to on the chart, and who it takes a question to when it needs a person.
- [Access](https://docs.ergoly.ai/workers/access.md): Who can talk to a worker, and which clients it serves. Set on the Clients tab.
- [Triaging](https://docs.ergoly.ai/workers/triaging.md): When a worker is slow, silent or stuck: what the Triage tab shows, and the three buttons that fix most things.
- [Channels](https://docs.ergoly.ai/workers/channels.md): Where a worker operates: Slack, email, and the web. And the events in those channels that make it act.
- [Slack](https://docs.ergoly.ai/workers/channels/slack.md): Each worker is a member of your workspace. Every channel it is in belongs to one client or to your team, and that decides what it knows there.
- [Internal channels](https://docs.ergoly.ai/workers/channels/slack/internal-channels.md): Your team's own channels. The worker answers from everything it knows, including every client.
- [Client channels](https://docs.ergoly.ai/workers/channels/slack/client-channels.md): A channel that belongs to one client. The worker answers there as your agency, from that client's world and nothing else.
- [DMs](https://docs.ergoly.ai/workers/channels/slack/dms.md): A direct message is always answered. Who you are decides which copy of the worker answers.
- [Group DMs](https://docs.ergoly.ai/workers/channels/slack/group-dms.md): A message to the worker and a few people at once. The people in it decide which client it is about.
- [Email](https://docs.ergoly.ai/workers/channels/email.md): Every worker has an email address and can send from it. Receiving is coming soon.
- [Receiving email](https://docs.ergoly.ai/workers/channels/email/receiving.md): A worker reading mail sent to its address, and acting on it.
- [Web](https://docs.ergoly.ai/workers/channels/web.md): Ways for other systems to reach a worker: a hook it listens on, triggers from connected tools, and the API.
- [Triggers](https://docs.ergoly.ai/workers/channels/web/triggers.md): An event inside a connected tool that starts a worker: a new deal, a new ticket, a changed row.
- [Events](https://docs.ergoly.ai/workers/channels/events.md): Everything that makes a worker act. Each one ends with an answer back where it came from.
- [Knowledge](https://docs.ergoly.ai/workers/knowledge.md): What a worker knows: its memory and its skills. Both are files you can read and edit.
- [Memory](https://docs.ergoly.ai/workers/knowledge/memory.md): Your worker remembers what you tell it. A note about Acme stays with Acme; a rule for the whole agency applies everywhere.
- [Skills](https://docs.ergoly.ai/workers/knowledge/skills.md): A saved way of doing a piece of work. Written by you in any editor, or by the worker when it has done something more than once.
- [Connections](https://docs.ergoly.ai/workers/connections.md): How a worker uses the tools it has been given. The tools themselves are set up under Work.
- [Clients](https://docs.ergoly.ai/clients.md): A customer of yours. Assign a worker to a client and that client gets its own copy, with its own memory and nothing of any other client's.
- [Adding a client](https://docs.ergoly.ai/clients/adding.md): Three ways: ask your AI Admin, press New Client, or let a worker create one when it joins a channel.
- [Assigning a worker](https://docs.ergoly.ai/clients/assigning-a-worker.md): Bind a worker to a client, with at least one channel or person. That creates the client's own copy of the worker.
- [Client separation](https://docs.ergoly.ai/clients/separation.md): What a client's copy of a worker can see, what it cannot, and what a client's contact can do.
- [Internal client channels](https://docs.ergoly.ai/clients/internal-channels.md): Backstage: a channel of your own where the team reviews a worker's drafts for a client before the worker is in front of that client.
- [Work](https://docs.ergoly.ai/work.md): What a worker does between conversations: tasks and routines, the tools it is connected to, approvals, and the pages it publishes.
- [Tasks](https://docs.ergoly.ai/work/tasks.md): A piece of work with someone who asked and someone doing it. Hand it to a worker or a person, follow it on its log, and say where the result goes.
- [Routines](https://docs.ergoly.ai/work/routines.md): A task that repeats. Describe it once, say where results go, and point it at every client it should run for.
- [Connections](https://docs.ergoly.ai/work/connections.md): The apps, keys and tool servers your company has connected, and who may use each one.
- [Connecting a tool](https://docs.ergoly.ai/work/connections/connecting-a-tool.md): Press Add Connection, pick the app, choose who may use it, and sign in or paste a key.
- [Placement](https://docs.ergoly.ai/work/connections/placement.md): Who may use a connection: the whole company, one worker, one client, or one worker for one client. The narrowest match wins.
- [Keys and tools](https://docs.ergoly.ai/work/connections/keys-and-tools.md): What happens when you paste a key, and what a worker can then do with the app.
- [Custom tools](https://docs.ergoly.ai/work/connections/custom-tools.md): Any tool server by its URL, or any API by its base URL, when the catalog does not list the app.
- [Credential safety](https://docs.ergoly.ai/work/connections/credential-safety.md): A worker never holds a password or a key. The credential is added to the request on the way out, by a part of Ergoly the worker cannot reach.
- [Approvals](https://docs.ergoly.ai/work/approvals.md): A worker asks before it acts when you tell it to, and on its own for anything hard to undo. The decision is recorded. The activity feed holds everything else.
- [Artifacts](https://docs.ergoly.ai/work/artifacts.md): A web page a worker publishes with a link: a report, a dashboard, a one-pager. Private to your company by default, or open to anyone with the link.
- [Collaboration](https://docs.ergoly.ai/work/artifacts/collaboration.md): Commenting on an artifact, and the worker picking the comments up.
- [Glossary](https://docs.ergoly.ai/glossary.md): Every term you'll meet while working with Ergoly's workers: what it is, what you use it for, and why it matters. They are the same words control and the rest of the docs use.
- [Technical details](https://docs.ergoly.ai/technical.md): What happens behind the words in these docs, for the engineer at your agency or anyone on the API.
- [How a worker runs](https://docs.ergoly.ai/technical/how-a-worker-runs.md): A worker is one identity. Each client it serves gets a separate running copy, and each message it handles is one turn.
- [Where knowledge lives](https://docs.ergoly.ai/technical/where-knowledge-lives.md): Memory and skills are files in five tiers, and when two tiers disagree the narrowest one wins.
- [How a channel reaches a worker](https://docs.ergoly.ai/technical/how-a-channel-reaches-a-worker.md): Every Slack message is routed to one copy of one worker by a fixed rule, before any model runs.
- [How credentials are held](https://docs.ergoly.ai/technical/how-credentials-are-held.md): A worker never holds a password or a key. A gateway puts the secret into the request on the way out.
- [Changelog](https://docs.ergoly.ai/changelog.md): New features, improvements and fixes, every week.
- [Efficient recurring tasks, clearer failures, and worker renames](https://docs.ergoly.ai/changelog/2026-11-02-scheduled-task-cost-and-reliability.md): Long-running recurring tasks are now more efficient and stay focused on the current run, a failed turn is no longer met with silence, renaming a worker updates its name in Slack, and new workers more reliably go to work.
- [Tasks launch, and webhooks that start work](https://docs.ergoly.ai/changelog/2026-10-26-tasks-launch-and-webhooks.md): Tasks are now the way work is handed between workers and people, with a board in the web app. Outside events, like a listing going down, can also start a worker's work through a webhook.
- [Hand work between workers, and safer key connections](https://docs.ergoly.ai/changelog/2026-10-19-tasks-and-key-connections.md): Work can now be handed between workers and people as a task, and connecting or replacing an API key gives clearer, more accurate results. A task scheduled from a DM now delivers its result by DM.
- [Workers that see whole messages, know your org, and adopt your skills](https://docs.ergoly.ai/changelog/2026-10-12-smarter-workers-whole-messages.md): Workers now see every part of a Slack message, know your org chart, can adopt skills you hand them, and can turn themselves back up after being quieted. Several causes of missed or unanswered messages are fixed.
- [Vendors on your org chart, and task runs that settle cleanly](https://docs.ergoly.ai/changelog/2026-10-05-vendors-on-org-chart.md): External companies can now appear on your org chart, and a task that fails at startup now settles cleanly instead of getting stuck.
- [Artifacts, approvals, and workers that manage their own tools](https://docs.ergoly.ai/changelog/2026-09-28-approval-flows-self-managed-connections.md): Workers can now publish shareable pages, handle approvals end-to-end in Slack, and connect their own tools — and each worker carries a responsibility scope and behaviors you control.
- [Workers can see images, and connections that stay connected](https://docs.ergoly.ai/changelog/2026-09-21-connections-fixes-image-read.md): Workers can now read and respond to images. A permission refusal no longer disconnects an integration, and connection setup is noticeably faster.
- [Connections: hundreds of apps, one page](https://docs.ergoly.ai/changelog/2026-09-14-composio-connections-launch.md): Workers can now connect to hundreds of third-party apps through a single Connections page, progress messages read like a person wrote them, and authenticated API calls go out correctly again.
- [Workers get their own email](https://docs.ergoly.ai/changelog/2026-09-07-email-launch-v2-hardening.md): Every worker can now send email from its own address, and workers are noticeably better at knowing what they know, reading Slack threads and recovering from errors.
- [The platform API, a simpler worker, and better scheduled tasks](https://docs.ergoly.ai/changelog/2026-08-31-agent-surface-platform-api.md): A full API for managing your Ergoly environment in code, a leaner and more consistent worker, and a scheduled-task overhaul with a thread per run and multi-client targeting.
- [Streamed replies, richer output, and a reliability sprint](https://docs.ergoly.ai/changelog/2026-08-24-streamed-turns-and-reliability.md): Workers now reply in a single updating message instead of a stream of interruptions, tables and file attachments work, and a wave of fixes closes the most common causes of a stuck worker.
- [Introduction](https://docs.ergoly.ai/api-reference/introduction.md): Read and change your own company's Ergoly environment from a terminal or a coding agent. One key, one header, one envelope.
- [The API](https://docs.ergoly.ai/technical/api.md): One key per company, one header, one envelope. The reference is served by the API itself.
- [Get your company](https://docs.ergoly.ai/api-reference/organization/get-your-company.md): Needs no query of its own — authenticating the request already resolved the organization, so this hands back what the gate found. It is the cheapest way to confirm a key before doing anything with it.
- [List chart placements](https://docs.ergoly.ai/api-reference/workers/list-chart-placements.md): Every place on your Company chart a Worker may sit under — a person's seat, a Worker's, a team, an open role — in the order the chart draws them, each with its title and the place it sits under. Pass one's `id` as `reportsTo.placementId` when you create a Worker. Nothing inside a vendor or a client…
- [Get the activity feed](https://docs.ergoly.ai/api-reference/activity/get-the-activity-feed.md): `?kind=` is exact. `?domain=` matches the leading segment of `kind`, so `?domain=api` is every write made through this API. `?actor=` takes a user id, or the literal `system` for rows with no person behind them — which is where your keys' own writes appear.
- [Get usage](https://docs.ergoly.ai/api-reference/usage/get-usage.md): `?window=30d` and `?days=30` ask the same question; either is accepted. Longer than 90 days is clamped to 90. `?tz=` must be an IANA name and decides where a day starts; it defaults to `UTC`. A zone this system does not recognize is refused rather than swapped for the default.
- [List workers](https://docs.ergoly.ai/api-reference/workers/list-workers.md): Newest first. Deleted Workers are excluded; their eworks and scheduled jobs are excluded everywhere else for the same reason.
- [Create a worker](https://docs.ergoly.ai/api-reference/workers/create-a-worker.md): The row exists when this returns and a provisioning run has started; poll `jobId` at `/api/v1/jobs/{id}`. When `currentStep` is `await_oauth_install`, open the job's `installUrl` in a browser as a Slack workspace admin — nothing here can finish that step for you. Approving it starts a second run, so…
- [Get the current worker](https://docs.ergoly.ai/api-reference/workers/get-the-current-worker.md): For a key that was minted for a Worker, this is that Worker — the same record and the same fields as `/api/v1/workers/{id}`, without needing the id. It is the call to make first, because a Worker's own id is what almost every other call takes: its channels and its eworks. A key held by a person rath…
- [Get a worker](https://docs.ergoly.ai/api-reference/workers/get-a-worker.md): 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 fres…
- [Update a worker](https://docs.ergoly.ai/api-reference/workers/update-a-worker.md): These columns are what the agent's identity file is composed from, so editing `displayName` changes who the agent says it is from its next turn. That is why editing the file by hand is refused and this is not. `roleTitle` and `description` take `null` to clear them. A change to any of the three is a…
- [Delete a worker](https://docs.ergoly.ai/api-reference/workers/delete-a-worker.md): The Worker stops serving immediately and drops out of every list here. Its Slack app configuration is left behind for an admin to remove by hand — the install is revoked, the app is not deleted.
- [Retry provisioning](https://docs.ergoly.ai/api-reference/workers/retry-provisioning.md): The usual answer to a failed run, and the way back from a stop. It re-provisions in place: the previous sandbox keeps serving until the new one is up. Poll the `jobId` it returns. `phase` says which half of the pipeline ran — before the Slack install, or after it.
- [Stop a worker](https://docs.ergoly.ai/api-reference/workers/stop-a-worker.md): Takes the Worker out of service without deleting it. Its eworks stop taking traffic; the row, its mappings and its history all stay. Stopping a stopped Worker is fine — it answers the same way. Bring it back with a re-provision, which is the call that costs a slot; stopping costs none, because it mi…
- [Get a provisioning job](https://docs.ergoly.ai/api-reference/jobs/get-a-provisioning-job.md): `status`, `currentStep` and the failure `error`. Poll after any 202 until `status` is terminal. A run sitting at `await_oauth_install` is waiting on a workspace admin, not stuck — open its `installUrl` in a browser as one. That install starts a SECOND run and leaves this one parked, so follow the re…
- [List a worker's copies](https://docs.ergoly.ai/api-reference/eworks/list-a-workers-copies.md): One core ework plus one per bound Client. An empty list means this Worker has no eworks; a 404 means no such Worker for this credential. The two are kept apart deliberately — deriving the first from the second would report another tenant's Worker as one of yours that happens to be empty.
- [Get a copy](https://docs.ergoly.ai/api-reference/eworks/get-a-copy.md): Tier, status, sandbox class, sleep state and the snapshot it was provisioned from, plus the provider ids worth quoting in a support thread. `sleepingAt` set is normal and needs no action — the next turn wakes it.
- [Read a memory tier](https://docs.ergoly.ai/api-reference/memory/read-a-memory-tier.md): Three answers, chosen by the query and never by the state of anything. No `repoId` lists the tiers this ework can reach — start here, it is how you learn the ids. `repoId` alone lists what is at `path`, the repository root by default. Adding `read` returns the file itself, with the `sha` a later wri…
- [Write a file](https://docs.ergoly.ai/api-reference/memory/write-a-file.md): Send exactly one of `content` (text) or `contentBase64` (bytes) — decoding bytes as text mangles them silently, so sending neither is refused rather than guessed. `changed: false` means the content was already identical and nothing was committed. Every running ework mounting the tier is told, and pi…
- [Write several files](https://docs.ergoly.ai/api-reference/memory/write-several-files.md): What a skill install is: the files under `skills/<name>/` written together, so no ework ever sees half a skill. Each file takes `content` or `contentBase64`, the same way a single write does. Use this rather than a loop of single writes whenever the files only make sense together.
- [Delete a file or folder](https://docs.ergoly.ai/api-reference/memory/delete-a-file-or-folder.md): `kind: "dir"` removes the directory and everything under it; uninstalling a skill is a `dir` delete of `skills/<name>`. A directory containing a path control owns is refused whole, rather than emptied around it.
- [List clients](https://docs.ergoly.ai/api-reference/clients/list-clients.md): Newest first. Every Client of your organization, bound or not.
- [Create a client](https://docs.ergoly.ai/api-reference/clients/create-a-client.md): Complete when it returns: the Client exists and its memory tier repository has been made, along with a private instance tier for each active Worker. No ework is created — that happens when you bind the Client to a Worker. A create that cannot make its repositories is rolled back rather than left hal…
- [Get a client](https://docs.ergoly.ai/api-reference/clients/get-a-client.md): Another organization's id answers 404, exactly as an unknown one does.
- [Update a client](https://docs.ergoly.ai/api-reference/clients/update-a-client.md): Send only what changes. `websiteUrl` and `shortDescription` take `null` to clear them. The slug is fixed once created.
- [Assign a client to a worker](https://docs.ergoly.ai/api-reference/clients/assign-a-client-to-a-worker.md): Creates that pair's client-tier ework and, in the same call, optionally maps channels and binds people to it. The routing rows are durable when this returns; `activation` says whether the agent behind them came up. A channel or a person already bound to a different Client is refused rather than re-p…
- [List Slack channels](https://docs.ergoly.ai/api-reference/channels/list-slack-channels.md): Every public room in the workspace — including the ones none of your Workers is in, which is what makes it a directory rather than a roster — plus the private rooms a Worker has been invited into. `?query=` ranks by name with an exact match first, so "#ops" never resolves to "#ops-archive". `memberW…
- [Create a Slack channel](https://docs.ergoly.ai/api-reference/channels/create-a-slack-channel.md): Opens a Slack channel on the CALLING worker's own identity, so only a worker's key can call it. It creates the room, maps the caller, maps then invites each of `workers`, and invites the person who asked — the sender of the caller's running turn, never a body field — then `people`. With no person as…
- [List channel mappings](https://docs.ergoly.ai/api-reference/channels/list-channel-mappings.md): Each row names the Slack channel and the Client it routes to. A `client` of `null` is a room marked internal, which routes to the Worker's core ework — not a row with data missing.
- [Map a channel](https://docs.ergoly.ai/api-reference/channels/map-a-channel.md): The bot joins the channel and its traffic routes to that Client's ework. Moving a channel already mapped to a different Client needs `confirm: true`, without which it is a `conflict`. A DM id (`D…`) is refused: a direct message routes by who is in it.
- [Classify a channel](https://docs.ergoly.ai/api-reference/channels/classify-a-channel.md): `internal` writes a mapping row with a null client and routes the room to the Worker's existing core ework — nothing is minted, and it answers **200**, because the row is the whole of the change. `client` binds the room and brings up that pair's ework, so it answers **202** and the agent may still b…
- [Unmap a channel](https://docs.ergoly.ai/api-reference/channels/unmap-a-channel.md): Removes the routing row and asks the bot to leave the room. `leftSlack` says whether Slack accepted that; a refusal there does not fail the call, because the routing decision is the durable half and it has already landed. To mark a room internal instead, classify it — an unmapped room routes nowhere…
- [Invite a worker to a channel](https://docs.ergoly.ai/api-reference/channels/invite-a-worker-to-a-channel.md): Mapping a channel decides where its traffic routes; this puts the bot in the room, which is the other half and the one Slack will not do by itself. Only a worker's own key can call it, and the invite is made on that worker's own bot token and nothing else. The Worker being added must already be mapp…
- [List tasks](https://docs.ergoly.ai/api-reference/tasks/list-tasks.md): 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.
- [Create a task](https://docs.ergoly.ai/api-reference/tasks/create-a-task.md): Without `scheduleKind`, opens a task held by the Worker in `workerId`, with an optional `description` and `dueAt`; the Worker is woken by it. With `scheduleKind`, schedules a job instead. `scheduleKind: "once"` takes an ISO `runAt`; `"cron"` takes a five-field `cronExpr` and a `timezone`. A `client`…
- [Get a task](https://docs.ergoly.ai/api-reference/tasks/get-a-task.md): The task as `listTasks` shows it, plus its log oldest first — the newest 200 entries, with `logOmitted` counting any older ones. An entry a key wrote shows the `platform` as its actor.
- [Hand off a task](https://docs.ergoly.ai/api-reference/tasks/hand-off-a-task.md): Name exactly one of `workerId` or `slackUserId`. Handing it to the holder it already has changes nothing and answers `changed: false`. A task that is one client's work can go only to a Worker serving that client, or to a person. A closed task cannot be handed on.
- [Comment on a task](https://docs.ergoly.ai/api-reference/tasks/comment-on-a-task.md): The comment is an entry on the log and wakes every Worker on the task. A closed task can still be commented on.
- [Change a task's state](https://docs.ergoly.ai/api-reference/tasks/change-a-tasks-state.md): `in_progress` starts it; `resolved`, `declined` and `cancelled` close it with that outcome. Only the holder may decline, so a key never can. A task already in that state answers `changed: false`.
- [Update a scheduled job](https://docs.ergoly.ai/api-reference/tasks/update-a-scheduled-job.md): Every field is optional; send only what changes. `enabled: false` parks a job without cancelling it, and `true` starts it again. Changing the schedule re-arms every target.
- [Cancel a scheduled job](https://docs.ergoly.ai/api-reference/tasks/cancel-a-scheduled-job.md): A soft delete: the job stops firing, drops out of the task list, and its run history survives. Its targets are left in place and fire nothing while the job is cancelled.
- [List a job's runs](https://docs.ergoly.ai/api-reference/tasks/list-a-jobs-runs.md): Newest first, sorted and paged on the run's own start time. `success` is `null` while a run is still in flight — which is not the same as `false`.
- [Add a target](https://docs.ergoly.ai/api-reference/tasks/add-a-target.md): The job fires once per target. A target may override the expression, the instant, the zone and where it posts; anything it does not override folds against the job's own schedule. An override naming a field this job's schedule kind does not use is refused.
- [Remove a target](https://docs.ergoly.ai/api-reference/tasks/remove-a-target.md): Removing the last target is refused with `conflict` — a job with no target fires nowhere, which is what cancelling the job is for.
- [List webhooks](https://docs.ergoly.ai/api-reference/webhooks/list-webhooks.md): Every inbound endpoint your organization has, revoked ones included — a retired webhook keeps its row so its delivery history stays readable, and `enabled: false` beside a `revokedAt` is what says which. No response here carries a secret. `?workerId=` narrows to one Worker.
- [Create a webhook](https://docs.ergoly.ai/api-reference/webhooks/create-a-webhook.md): Returns the URL to POST to and the secret to send with it. `surfaceKind: "channel"` needs a `channelId` already mapped to this Worker — an unmapped room, and a DM id, are both refused; `"dm"` needs the `slackUserId` of the person. On a room mapped to a client, `workClientId` names that client. For a…
- [Get a webhook](https://docs.ergoly.ai/api-reference/webhooks/get-a-webhook.md): The endpoint's configuration and its URL. Never its secret: the row holds a hash, so there is nothing here to return.
- [Update a webhook](https://docs.ergoly.ai/api-reference/webhooks/update-a-webhook.md): Every field is optional; send only what changes. `enabled: false` makes every delivery answer 410 without retiring the endpoint, and `true` starts it again. A change takes effect on the next delivery.
- [Revoke a webhook](https://docs.ergoly.ai/api-reference/webhooks/revoke-a-webhook.md): The endpoint stops answering: every later delivery is a 410. The row stays, so its delivery history survives and the webhook keeps appearing in the list marked revoked.
- [Rotate a webhook secret](https://docs.ergoly.ai/api-reference/webhooks/rotate-a-webhook-secret.md): Issues a new secret and shows it once. The URL does not change. `secretKind: "link"` with `linkAcknowledged: true` issues a link secret and answers its `link`; without `secretKind`, the new secret is a header one, even on a link webhook.
- [List deliveries](https://docs.ergoly.ai/api-reference/webhooks/list-deliveries.md): Every inbound POST leaves a row, whether it was accepted, refused or rate-limited, so "it fired and nothing happened" is answerable here. Bodies are not stored — the ledger records that a delivery arrived and how big it was, and the payload went to the agent.
- [List connections](https://docs.ergoly.ai/api-reference/connections/list-connections.md): Newest first, across all four types. `workerId` and `clientId` narrow to connections scoped to exactly that Worker or Client — they do not answer what that Worker can resolve, so org-wide connections it also reaches are not included. `?view=apps` lists the CONNECTED APPS instead: each is an app a pe…
- [Create a connection](https://docs.ergoly.ai/api-reference/connections/create-a-connection.md): Two shapes, told apart by `app`. WITHOUT it, this stores a secret: `value` is write-only, it goes in here and no route gives it back; give at least one host unless the key already has some — a credential no host points at is never injected by the gateway, so it would sit there doing nothing; a key a…
- [Get a connection](https://docs.ergoly.ai/api-reference/connections/get-a-connection.md): Everything the Connections page shows for it, in whichever of the two shapes the id names: a stored secret's scope, hosts and connection state by `type`; or a connected app's `app`, `status` and `placements`. Nothing it does not: no stored value, no client secret, in any form. A well-formed id belon…
- [Update a connection](https://docs.ergoly.ai/api-reference/connections/update-a-connection.md): Name one or more of `key`, `kind`, `scope` and `internalOnly`. Each is a separate guarded write applied in that order, and the first refusal stops the rest — so a body naming several fields can land some of them and then be refused, and the message says which already applied. `internalOnly` and a cl…
- [Delete a connection](https://docs.ergoly.ai/api-reference/connections/delete-a-connection.md): What this does depends on what the connection is. A plain secret is deleted, and its host mappings come down with it if no other variant of the key survives. A connected OAuth account is DISCONNECTED: the token is revoked with the provider first, which is the part that matters, then the row and its…
- [Rotate a connection](https://docs.ergoly.ai/api-reference/connections/rotate-a-connection.md): The key and every host mapping are unchanged, so anything already naming this credential keeps working. The new value is write-only, like the original. Rotation is refused on a system-managed connection.
- [List hosts](https://docs.ergoly.ai/api-reference/connections/list-hosts.md): Every host in one answer — a credential has a handful, not a stream, so there is no cursor. Hosts attach to the connection's key, so every scoped variant of that key returns the same list.
- [Add a host](https://docs.ergoly.ai/api-reference/connections/add-a-host.md): The hostname must be bare: no scheme, path, port, userinfo or wildcard. It is lowercased and any trailing dot dropped before it is stored, so what you send and what the gateway matches are the same thing. A host already mapped to another connection in this organization is a `conflict` — one host res…
- [Remove a host](https://docs.ergoly.ai/api-reference/connections/remove-a-host.md): Addressed by hostname, canonicalized the same way it was when added. A host mapped to a different connection answers 404 rather than a refusal: it is not this connection's to remove, and saying more would confirm it exists elsewhere.
- [Get a connect URL](https://docs.ergoly.ai/api-reference/connections/get-a-connect-url.md): A consent screen needs a browser and a person, so this returns a link to open rather than claiming to finish. The link carries a single-use nonce instead of an Ergoly session, which means it can be opened in a private window signed into whichever account should be connected — usually the reason you…
- [Get a sign-in link](https://docs.ergoly.ai/api-reference/connections/get-a-sign-in-link.md): For an account that expired, a consent that never finished, or a failed one. The old account is taken down first — revoked if it still works — and a new hosted sign-in is minted into the same connection, which keeps its id, name and placements. Until the person finishes consent the connection is `pe…
- [Add a placement](https://docs.ergoly.ai/api-reference/connections/add-a-placement.md): A placement is where a connected app may be used — the whole company, one Worker, one Client, or one Worker for one Client — and a connection may have several. Adding one changes which eworks' sessions carry the app, and the answer's `sessions` reports each one reached: what it gained, what it lost,…
- [Remove a placement](https://docs.ergoly.ai/api-reference/connections/remove-a-placement.md): Removes one placement and leaves the rest. The eworks that lose the app have their sessions updated before this answers, and `sessions` names them. A placement that belongs to a different connection answers 404 rather than a refusal — it is not this connection's to remove. Removing the last placemen…
- [Connect an MCP server](https://docs.ergoly.ai/api-reference/connections/connect-an-mcp-server.md): Ergoly discovers the server's metadata, registers itself dynamically, and starts consent. Read `mode` before doing anything else: `oauth` means open `authorizeUrl` and nothing is connected yet, while `no-auth` means the server wanted no credential and the connection is ALREADY complete — handshaken,…
- [Finish an MCP connection](https://docs.ergoly.ai/api-reference/connections/finish-an-mcp-connection.md): A connection reporting `mcpStatus: "needs_reconnect"` holds a valid registration but no address to send anything to, so it can never work as it stands. This tries to work the address out and proves it with a real handshake. If it answers `conflict`, retrying will not help — disconnect and connect ag…
- [Get a provider app](https://docs.ergoly.ai/api-reference/connections/get-a-provider-app.md): The client id and the redirect URI to register with the provider. The client secret is write-only and has no field here. A provider with nothing configured is a 200 saying `configured: false`, not a 404 — the question has an answer either way.
- [Set a provider app](https://docs.ergoly.ai/api-reference/connections/set-a-provider-app.md): `clientSecret` is required the first time and optional afterwards: send it to rotate, omit it to keep the stored one. The redirect URI is derived by Ergoly and returned for you to register with the provider — it is never something you set. 201 when this created the app, 200 when it rotated one.
- [Delete a provider app](https://docs.ergoly.ai/api-reference/connections/delete-a-provider-app.md): Cascades. Every account connected through this app is torn down first, because the client secret their tokens are refreshed with is about to stop existing and leaving them would leave connections nothing can renew. `removedConnections` says how many went.
- [Get your OAuth client](https://docs.ergoly.ai/api-reference/connections/get-your-oauth-client.md): Whether you have brought your own OAuth client for this catalog app, and the one redirect URI to register on it at the provider. Nothing about the client's credentials is here or anywhere on this API. Not configured is a 200 saying `configured: false`, not a 404.
- [Set your OAuth client](https://docs.ergoly.ai/api-reference/connections/set-your-oauth-client.md): Every hosted sign-in for this app then goes through your client rather than Ergoly's, so the consent screen shows your name and the tokens are yours. Register `redirectUri` on the client at the provider first. Both fields are required every time: the secret is handed to Composio and held nowhere on…
- [Delete your OAuth client](https://docs.ergoly.ai/api-reference/connections/delete-your-oauth-client.md): Deletes the client id and secret from Composio, and hosted sign-ins for the app go back through Ergoly's client. Refused with `conflict` while any connection still signs in through it — the response names them — because Composio takes every account made through the client down with it: remove or rec…

## OpenAPI Specs

- [openapi](/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.