Slack API

Slack Web API

Help the developer discover the right Web API method, read its contract, and call it correctly. Slack exposes hundreds of methods named in family.method dot notation (e.g. chat.postMessage, conversations.history) at https://slack.com/api/<method>. Every method's doc page follows a fixed URL pattern, so the contract for any method is always one fetch away.

If $0 is provided, it is either a full method.name (jump to Step 2 to read its contract) or a family name (go to Step 1 and find it in the index).

Critical rules:

• Verify a method name and its required scopes against its doc page before calling it — never invent method names or guess scopes. Method names use family.method dot notation.
• Every response has a top-level ok boolean. Always check ok before using the result; on ok: false, read the error string.
• Method names, scopes, rate tiers, and arguments come from the live doc page (https://docs.slack.dev/reference/methods/<method-lowercased>.md). The docs are the source of truth — discover from the live index, read the contract from the method's own page.

DO NOT rules:

• DO NOT assume a method is GET — many are POST. Check the doc page.
• DO NOT hardcode bearer tokens into committed code or share them in plain text.
• DO NOT use deprecated methods (files.upload, dialog.open, rtm.*, oauth.access, search.*, stars.*, reminders.*) without checking the replacement — a deprecated method's own doc page names what supersedes it; prefer the replacement for new apps.
• DO NOT paginate by incrementing a page number — Slack uses opaque cursors (see Step 5).

Execution posture — run reads, confirm writes:

• Read-only methods (*.list, *.info, *.history, conversations.members, auth.test, etc.) may be run directly to help the developer.
• State-changing or destructive methods (chat.postMessage/update/delete, any *.delete/*.remove/*.kick/*.archive, and all admin.*) — prepare the exact command and confirm with the developer before running it.

Fast Path (for clear, specific requests)

If the developer already knows the method — they named it, pasted a https://slack.com/api/<method> URL or a docs.slack.dev/reference/methods/<method> link, or gave a family.method — skip discovery:

1. Go to Step 2 to read the method's contract.
2. Go to Step 4 to call it (honoring the execution posture above).

Full-workflow indicators (start at Step 1):

• "Which method does X?" / "How do I list/fetch/post … via the API?"
• The capability is known but the method name is not.
• Exploratory questions about what the API can do.

Step 1: Identify the Method (Discover)

Map the developer's intent to a family, then to a candidate method.

Browsing the index

WebFetch the live method index:

https://docs.slack.dev/reference/methods.md

It lists every Web API method in family.method notation with a one-line description and a link to that method's own doc page. It is complete and always current — scan it for a candidate, then follow the method's link into Step 2 to read the contract (the index has descriptions only; rate tier, scopes, token type, and pagination all live on the per-method page).

Never publish or call a method name you have not seen on a live page.

Searching the docs

When you would rather search by keyword than scan the index, and the Slack CLI is available, use the slack:slack-cli skill — Step 3: Searching Documentation (slack docs search) — to query Slack's docs from the terminal. That step covers the command and flags; results will point you to the method's reference page, which you then read in Step 2. Without the CLI, WebFetch the index (https://docs.slack.dev/reference/methods.md) and scan it instead.

Step 2: Read the Method Contract (Navigate)

Fetch the method's doc page with WebFetch. Either follow the method's link from the index (Step 1) or construct the URL — the path segment is all-lowercase and ends in .md:

https://docs.slack.dev/reference/methods/<method-lowercased>.md

For example, conversations.members → https://docs.slack.dev/reference/methods/conversations.members.md, and chat.postMessage → https://docs.slack.dev/reference/methods/chat.postmessage.md. When in doubt about casing, follow the index link rather than building the URL by hand.

Every method page documents, consistently:

• HTTP method (GET / POST) and the endpoint https://slack.com/api/<method>
• Required OAuth scopes and the token type (bot xoxb- vs user xoxp-)
• Arguments — required vs optional, with types
• An example request and response
• An errors table (method-specific codes)
• The rate-limit tier

Extract the required arguments and required scopes before calling. For what these cross-cutting concepts mean in general — beyond what the method page states — the canonical references are: the response envelope, POST bodies, and auth at https://docs.slack.dev/apis/web-api.md; pagination at https://docs.slack.dev/apis/web-api/pagination.md; and rate-limit tiers at https://docs.slack.dev/apis/web-api/rate-limits.md.

Step 3: Authenticate and Scope

Calling any non-public method requires a token with the right scopes and type. This skill's job here is to determine, from the contract you read in Step 2, which token type and scopes the method needs — independent of how you ultimately send the token.

From the contract you read in Step 2:

• Confirm the token type — a bot token cannot call a user-only method (the method's doc page states which token types it accepts), and vice versa. For what each token prefix (xoxb-, xoxp-, xapp-) is and when to use it, see https://docs.slack.dev/authentication/tokens.md.
• Note the required scopes. If a call later fails with missing_scope, the response's needed and provided fields name the gap — add the needed scope to the app manifest and reinstall the app.
• admin.* methods require an Enterprise Grid org-level token.

A couple of methods need no auth: api.test (connectivity), auth.test (validates whatever token you do send) and blocks.validate.

You need a token only when the method requires one. There are two ways to get one — pick whichever fits the developer's setup. The Slack CLI is optional: if the developer does not have it and prefers not to install it, take Path B rather than forcing an install.

Path A: Use the Slack CLI (if installed or wanted)

The CLI supplies an authenticated session, so once the developer is logged in you can call methods without handling a token yourself (Step 4, "Via the Slack CLI").

Use the slack:slack-cli skill — Step 1: Detect the Slack CLI — to check whether the public Slack CLI is installed and resolve its command name. That step also proposes installing the CLI when it is absent. The fingerprint check, alias fallback, and install instructions all live there; do not duplicate them here.

Once resolved, use the detected command name for all CLI commands in this skill. We refer to it as SLACK_CMD — substitute the actual resolved command name everywhere you see SLACK_CMD.

Use the slack:slack-cli skill — Step 5: Authentication (slack auth) — to check the developer's login state and, if needed, walk them through slack login. Authentication mechanics live there.