Skip to main content

​
Providers

A provider is an outside service that your organization connects to Work. Each organization has its own settings, and an Owner or a member with Manage on the organization sets them. Set one with PUT /v1/settings/providers/{provider}. Send settings (plain values) and secrets (keys and passwords). Secrets are write-only: Work never returns them. GET /v1/settings/providers shows which providers are set up. POST /v1/settings/providers/email/test sends a test email. Email and calendar actions that an Agent or an automation proposes wait for a gate, if you set one.

​
Directory sync

Directory sync adds the people of your Google or Microsoft directory as members.
  • Set up the Directory provider first, with the vendor (Google is the default) and its credentials.
  • Call POST /v1/integrations/directory/sync. It needs Manage on the organization.
  • The result tells you how many people were imported and how many were skipped. Running it again adds only new people.
  • If Directory is not set up, the call answers 501 (“Directory sync is not configured for this organization”).

​
Outbound connections

Register a connection with POST /v1/integrations: a name, a type (for example a webhook), a target address and, if needed, a secret. You can enable, disable, change or delete it later. The target is shown shortened in responses, and the secret is never returned. POST /v1/email sends an email through a registered email connection. Each person can also connect their own Google account (/v1/integrations/google/connect) and disconnect it. GET /v1/me/integrations lists what you connected and GET /v1/me/calendar/events reads your calendar events.

​
Apps that use your account

An MCP client or another app that you signed in with is listed under GET /v1/oauth/clients. Revoke one with DELETE /v1/oauth/clients/{id} and it stops working at once. See Work MCP tools.

​
Webhooks

An automation can send data out with the CallWebhook action. See Automations reference. Public forms are the way to receive data from outside: see Views, forms and dashboards.

​
Import from Excel

Upload an .xlsx file as multipart/form-data.
  • POST /v1/imports/excel makes a new board: its columns and every row, in one step.
  • POST /v1/boards/{boardId}/imports/excel adds rows to an existing board.
If anything fails, nothing is created: you never get half a board. Send an Idempotency-Key header so a retry does not import twice. A file over the size limit is refused before it is read.

​
Files and docs

An item can have attachments. Upload is in two steps: ask for an upload address, send the file, then finalize. Download uses a short-lived signed address (POST /v1/attachments/{id}/signed-url). Files are stored per organization and are not reachable without that address. Docs take uploads the same way.

​
Realtime

Open boards update without a refresh. Work uses a SignalR hub at /hubs/board.
  • A client first asks for a hub ticket: POST /v1/hub-ticket, with its normal sign-in. The ticket is valid for 60 seconds and works only for the hub. Your session token is never put in a URL.
  • The client joins the groups of the boards it may read. A member only receives events for those boards.
  • A board also shows who else is looking at it (presence).
  • Most events carry no data. They tell the client to read the board again, so a live update never leaks a value.
  • When a member is suspended or removed, their open connection is closed.
Source: worksong-ai/worksong:services/work/src/Boardy.Api/Program.cs@9f0684f, worksong-ai/worksong:services/work/src/Boardy.Adapters/Http/DirectoryConnectors.cs@9f0684f, worksong-ai/worksong:services/work/src/Boardy.Api/Realtime/BoardHub.cs@9f0684f. Docs version: Worksong 2.0 with Work 1.2.