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-developer: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-developer: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-developer:slack-cli skill — Step 5: Authentication (slack auth) — to check the developer's login state and, if needed, walk them through slack login (which is interactive and must run in a separate terminal window). Authentication mechanics live there.

Path B: No CLI — bring your own token

You do not need the CLI to call a method. Get a token of the type you determined above from the app's OAuth & Permissions page in the Slack app config (https://api.slack.com/apps → your app → OAuth & Permissions → OAuth Tokens): the Bot User OAuth Token (xoxb-…) or the User OAuth Token (xoxp-…). That page also lists the scopes currently granted — confirm the ones from Step 2 are present. Then send that token with curl or an SDK in Step 4 ("Via raw HTTP" / "Via an SDK").

---

Step 4: Call the Method (Manage)

First apply the execution posture: if the method changes state (post/update/delete/archive/kick, or any admin.*), show the developer the exact command and get a yes before running it. Read-only calls can be run directly.

Via the Slack CLI (if installed)

To call a method from the terminal, use the slack-developer:slack-cli skill — Step 4: Calling Web API Methods (slack api). That step covers the SLACK_CMD api <method> key=value … syntax so that it is not repeated here. Pass the required arguments you gathered from the method's doc page in Step 2.

The CLI uses the developer's authenticated session, so it is the simplest path once they are logged in (Step 3).

Via raw HTTP (curl)

Use the Bash tool when the developer wants a raw request or isn't using the CLI. Send the token in the Authorization header — the bot or user token from Step 3 (Path B, or the CLI session).

Form-encoded (the default for most methods):

curl -s -X POST 'https://slack.com/api/conversations.list' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -d 'types=public_channel&limit=200'

JSON body (for methods taking complex arguments like blocks, view, attachments, metadata):

curl -s -X POST 'https://slack.com/api/chat.postMessage' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"channel":"C0123456789","text":"Hello from the API"}'

Check the method's page for which content type it expects. With form encoding, a structured argument is passed as a JSON-encoded string value (e.g. blocks=[...]).

Via an SDK

In Bolt and the Slack SDKs, each method is a client function whose arguments match the doc page's argument table:

• JavaScript: await client.chat.postMessage({ channel, text, blocks })
• Python: client.chat_postMessage(channel=channel, text=text, blocks=blocks)

(Note the JS dot form chat.postMessage vs the Python underscore form chat_postMessage.) To construct the blocks/view payload these calls take, use the slack-developer:block-kit skill — this skill treats that payload as an opaque argument and focuses on the method call around it.

---

Step 5: Handle Pagination

Methods that return collections use cursor pagination, not page numbers. A method's doc page states whether it paginates, and the full list of cursor-paginated methods is under Methods supporting cursor-based pagination at https://docs.slack.dev/apis/web-api/pagination.md:

1. Call with a limit (page size — check the method's max).
2. Read response_metadata.next_cursor from the response.
3. If it is non-empty, call again with cursor=<next_cursor>.
4. Repeat until next_cursor comes back empty.

# First page
curl -s -X POST 'https://slack.com/api/conversations.history' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -d 'channel=C0123456789&limit=200'

# Next page — pass the cursor from response_metadata.next_cursor
curl -s -X POST 'https://slack.com/api/conversations.history' \
  -H 'Authorization: Bearer xoxb-YOUR-TOKEN' \
  -d 'channel=C0123456789&limit=200&cursor=dXNlcjpVMDYxTkZUVDI='

Cursors are opaque — never construct, parse, or reuse an old one.

---

Step 6: Handle Rate Limits and Errors

When ok is false, branch on the error string:

• For method-specific codes, read the errors table on the method's doc page (Step 2) — it lists every error that method returns, including cross-cutting ones like not_authed, invalid_auth, missing_scope, channel_not_found, and invalid_arguments.
• For what the envelope itself means (ok, error, warning, response_metadata), see Evaluating responses at https://docs.slack.dev/apis/web-api.md.
• response_metadata.messages often pinpoints a malformed argument.

Rate limits: on HTTP 429 / error: "ratelimited", honor the Retry-After response header (seconds) — wait, then retry. Do not retry in a tight loop. Each method's tier (1–4 or special) caps calls per minute; the tier table is at https://docs.slack.dev/apis/web-api/rate-limits.md, and newer non-Marketplace apps face stricter caps on some methods, so trust the method's own page for the exact number.

---

Notes

• Slack Lists methods use the slackLists.* prefix — a bare lists.* name does not exist.
• Scope: this skill owns the method layer — which method, its contract, and the call around it. CLI auth and calls are delegated to slack-developer:slack-cli; Block Kit payloads to slack-developer:block-kit.