Claude Tag API

Claude Tag è Claude che lavora come un collega in Slack: qualcuno menziona Claude in un canale e Claude risponde nel thread. La Claude Tag API ti consente di leggere e modificare, dai tuoi sistemi, le impostazioni di Claude Tag che altrimenti un proprietario dell'organizzazione imposta manualmente in claude.ai > Organization settings > Claude Tag. Usala per attivare Claude canale per canale da un flusso di approvazione, mantenere la tua configurazione sotto controllo di versione o verificare cosa si applica in ogni canale.

Claude Tag è un prodotto di claude.ai. Questa API lo gestisce per un'organizzazione Claude Enterprise e non ha nulla a che fare con i workspace di Claude Platform, l'utilizzo dell'API o la Claude Console.

Endpoint

L'API espone 18 endpoint distribuiti su cinque risorse:

Questa versione copre Slack. La connessione e disconnessione di un workspace Slack, la creazione e modifica degli Access bundle, i limiti di spesa e ogni impostazione di Claude Tag diversa dalle cinque in Impostazioni restano in claude.ai.

Prerequisiti

• La tua organizzazione deve avere un piano Claude Enterprise, con Claude Tag configurato e almeno un workspace Slack connesso.
• Il tuo proprietario principale crea una chiave Admin API con lo scope read:claude_tag, lo scope write:claude_tag o entrambi in claude.ai > Organization settings > API. Consulta Creare una chiave API Admin.
• Ogni richiesta include tre header: x-api-key, anthropic-version: 2023-06-01 e anthropic-beta: claude-tag-2026-09-28.

Gli SDK Python, TypeScript, C#, Go, Java, PHP e Ruby espongono questi endpoint sotto client.beta.organization.claude_tag, e la CLI ant sotto ant beta:organization:claude-tag; inviano per te gli header anthropic-version e anthropic-beta. Gli esempi in questa pagina usano il client predefinito di ciascun SDK che, come la CLI, legge la chiave Admin API dalla variabile d'ambiente ANTHROPIC_API_KEY; gli esempi curl leggono la chiave dalla stessa variabile e la passano nell'header x-api-key. Quando un SDK o la CLI recupera altre pagine per te, limit imposta la dimensione della pagina, non il totale (consulta Paginazione).

Le chiavi API appartengono all'organizzazione e continuano a funzionare anche dopo che la persona che le ha create se ne va. Non condividerle e non inserirle nel controllo del codice sorgente.

Avvio rapido

Elenca i workspace Slack che la tua organizzazione ha connesso a Claude Tag:

client = anthropic.Anthropic()

workspaces = client.beta.organization.claude_tag.slack_workspaces.list()

# Recupera automaticamente altre pagine quando necessario.
for workspace in workspaces:
    print(f"{workspace.id}: {workspace.slack.team_id}")

{
  "data": [
    {
      "type": "slack_workspace",
      "id": "slws_011CZkZnWa7xPc3uJfZe5LgT",
      "slack": {
        "team_id": "T01ABCD2EFG"
      },
      "settings": {
        "enabled": null,
        "instructions": "Answer in English unless asked otherwise.",
        "model": null,
        "environment_id": null,
        "guest_policy": null
      },
      "agent_id": "cagt_011CZkZrFy4aSg8uMkDt9PqW",
      "created_at": "2026-09-02T17:04:11Z",
      "updated_at": "2026-10-06T09:41:53Z"
    }
  ],
  "next_page": null
}

Un'impostazione che vale null non è impostata su questo workspace, quindi il workspace la eredita. Consulta Impostazioni memorizzate ed effettive.

Scope

Una chiave può avere entrambi gli scope. Un'integrazione che cerca un canale e poi lo modifica ha bisogno di entrambi. Nessun altro scope concede l'accesso a questi endpoint.

La chiave deve appartenere all'organizzazione nel suo complesso. L'organizzazione è sempre quella a cui appartiene la chiave, e nessuna richiesta ne specifica una. Una richiesta che invia l'header anthropic-workspace-id restituisce 400, perché nulla qui appartiene a un workspace di Claude Platform.

Concetti chiave

Nomi in questa pagina e in claude.ai

Canali e workspace configurati

Un canale o workspace è configurato ("set up") quando Claude Tag conserva un record di impostazioni per esso. Solo un canale o workspace configurato ha un id, e solo questi vengono elencati: è Slack, non questa API, a conservare l'elenco completo dei canali di un workspace.

• Un workspace viene configurato quando un proprietario dell'organizzazione lo connette in claude.ai. Nessun endpoint configura o rimuove un workspace.
• Un canale viene configurato in claude.ai, al primo utilizzo di Claude in esso, oppure con Configurare un canale.
• I valori predefiniti Slack vengono configurati la prima volta che qualcuno configura Claude Tag: un proprietario connette un workspace Slack, oppure un membro accede a Claude in Slack o lo usa per la prima volta.

La tua organizzazione possiede un workspace finché la sua connessione è attiva, e possiede i canali al suo interno. Un canale o workspace che non possiedi restituisce lo stesso 404 di uno che non esiste.

ID

Conosci un canale tramite gli ID che Slack ti mostra. Cerca il suo id una volta con Trovare un canale tramite i suoi ID Slack, poi memorizza e usa l'id.

Un id non cambia finché il canale o workspace resta configurato, qualunque cosa tu modifichi su di esso, con un'eccezione descritta in Modalità di sola lettura. Un canale o workspace che viene rimosso e configurato di nuovo ha un nuovo id, e quello vecchio continua a restituire 404. Quando un id memorizzato restituisce 404 senza error_code, ottieni i valori predefiniti Slack con la stessa chiave e gli stessi header. Quella richiesta non specifica alcun canale o workspace, quindi qualsiasi stato diverso da 404 significa che l'id non esiste più: trova di nuovo il canale o workspace tramite i suoi ID Slack. Un 404 anche lì non dice nulla sull'id: conserva i valori id memorizzati e consulta Risposte di errore.

agent_id (con prefisso cagt_) è il modo in cui la Compliance API identifica lo stesso canale o workspace, sia come proprietario delle sessioni che Claude ha eseguito lì sia negli eventi dell'Activity Feed. Dura quanto l'id.

Impostazioni

Ogni livello di impostazioni memorizza le stesse cinque impostazioni, tutte facoltative:

model e environment_id vengono verificati quando li scrivi e non più in seguito: se il modello o l'ambiente cambiano successivamente, entrambe le viste continuano a restituire il valore memorizzato.

Se un proprietario dell'organizzazione ha assegnato un livello di impostazioni a un pool di runner self-hosted in claude.ai, il suo environment_id restituisce l'ID del pool, che inizia con ccpool_. Questa API non può impostare un pool di runner e restituisce 400 per una richiesta che modifica o cancella environment_id su un livello di impostazioni che ne memorizza uno.

Impostazioni memorizzate ed effettive

Le impostazioni esistono su tre livelli: il canale, il workspace in cui si trova il canale e i valori predefiniti Slack della tua organizzazione. Ogni livello memorizza solo ciò che è stato impostato su di esso. L'API ti offre due viste:

• La vista memorizzata (Ottenere un canale, Ottenere un workspace) contiene ciò che il canale o workspace stesso memorizza. Un'impostazione non impostata lì vale null. Usala per confrontarla con la configurazione che conservi altrove.
• La vista effettiva (Ottenere le impostazioni effettive di un canale, Ottenere le impostazioni effettive di un workspace) contiene ciò che si applica una volta considerati tutti i livelli, e sources indica il livello da cui proviene ciascun valore. Usala per le verifiche, o per scoprire perché Claude si comporta in un certo modo in un canale.

Ogni impostazione viene risolta separatamente:

Ad esempio, un'organizzazione memorizza delle istruzioni nei suoi valori predefiniti Slack, disattiva Claude su un workspace e imposta un modello su un canale di quel workspace. La vista effettiva del canale mostra i tre valori e la provenienza di ciascuno:

{
  "type": "slack_channel_effective",
  "id": "slch_011CZkZmRt4vNq8sHbYw2KdX",
  "settings": {
    "enabled": false,
    "instructions": "Be brief.",
    "model": "claude-opus-5-5",
    "environment_id": null,
    "guest_policy": { "type": "restrict" }
  },
  "sources": {
    "enabled": {
      "type": "slack_workspace",
      "slack_workspace_id": "slws_011CZkZnWa7xPc3uJfZe5LgT"
    },
    "instructions": [{ "type": "slack_defaults" }],
    "model": {
      "type": "slack_channel",
      "slack_channel_id": "slch_011CZkZmRt4vNq8sHbYw2KdX"
    },
    "environment_id": { "type": "default" },
    "guest_policy": { "type": "default" }
  }
}

Una fonte è una delle seguenti:

sources.instructions è un elenco, dal più ampio al più specifico, di ogni livello che contribuisce con del testo, ed è vuoto quando nessuno lo fa. L'ID su una fonte può essere null in un'organizzazione che raggiunge il canale tramite una connessione Slack Enterprise Grid anziché tramite il workspace del canale stesso.

Modificare le impostazioni

I tre endpoint di aggiornamento e Configurare un canale accettano un oggetto settings secondo le stesse regole:

• Un'impostazione che ometti resta invariata. {"settings": {"enabled": false}} disattiva Claude e lascia le altre quattro impostazioni come sono.
• Un'impostazione che invii come null viene cancellata, quindi il livello torna a ereditarla.
• Tutto o niente. Se un qualsiasi valore in una richiesta viene rifiutato, nessuna impostazione della richiesta viene memorizzata.
• Sicuro da ripetere. Ogni modifica lascia la risorsa come l'ha lasciata la prima richiesta identica, quindi nessun endpoint accetta un Idempotency-Key. Una richiesta che non altera nulla non scrive nulla e non registra alcun evento nell'Activity Feed.
• Vince l'ultima scrittura. Nessuna richiesta accetta una precondizione. Due chiamanti che leggono ciascuno una risorsa e poi modificano la stessa impostazione si sovrascrivono a vicenda. Un 409 viene restituito solo quando un'altra modifica si sovrappone alla tua richiesta mentre è in esecuzione; nulla della tua richiesta è stato memorizzato, quindi leggi di nuovo la risorsa e invia di nuovo la modifica se è ancora necessaria.

Una modifica a guest_policy su un canale può terminare le sessioni in esecuzione in quel canale. Terminano in background e la risposta non attende che ciò avvenga.

Livelli personalizzati

Un livello di impostazioni è personalizzato ("configured") una volta che una persona o una chiave ha modificato un'impostazione su di esso o vi ha collegato un Bundle. Da quel momento resta personalizzato, anche dopo che ogni impostazione è stata cancellata e ogni Bundle scollegato. Un canale configurato dal primo utilizzo di Claude, o tramite questa API senza alcuna impostazione, non è personalizzato fino alla sua prima modifica o al suo primo Bundle. Questo conta in due casi: solo un canale personalizzato può essere rimosso, e solo un canale non personalizzato può ricevere un nuovo id (consulta Modalità di sola lettura).

Modalità di sola lettura

API / Terraform read-only mode è un'impostazione che un proprietario dell'organizzazione attiva e disattiva nelle impostazioni di Claude Tag di claude.ai. Il nome descrive claude.ai e Slack: mentre la modalità è attiva, questi rifiutano le modifiche di una persona a ciò che questa API gestisce, quindi solo le chiavi apportano tali modifiche. Non rende questa API di sola lettura. Ogni endpoint in questa pagina risponde allo stesso modo sia che la modalità sia attiva sia che sia disattivata, e nessun endpoint la legge o la modifica.

Mentre la modalità è disattivata, persone e chiavi modificano le stesse impostazioni e collegano e scollegano gli stessi Bundle, e ogni modifica sostituisce ciò che è memorizzato. Attivala se la tua pipeline deve essere l'unica fonte di modifiche.

Mentre la modalità è attiva, claude.ai e Slack rifiutano:

• La modifica di una qualsiasi delle cinque impostazioni su un canale, un workspace o i valori predefiniti Slack.
• La configurazione di un canale, la rimozione di un canale o la disconnessione di un workspace in claude.ai.
• Il collegamento di un Bundle a un canale o workspace, il suo scollegamento o l'eliminazione di un Bundle collegato a uno di essi.

Alcune cose restano possibili in entrambi i casi: un proprietario può comunque connettere un nuovo workspace, creare e modificare Bundle e modificare le impostazioni di Claude Tag che questa API non gestisce. Il primo utilizzo di Claude configura comunque un canale, l'eliminazione di un canale in Slack lo rimuove comunque e la disinstallazione dell'app Slack di Claude disconnette comunque quel workspace.

Mentre la modalità è disattivata, configurare in claude.ai un canale che è già configurato e non è personalizzato può sostituire il record del canale. Il canale ha quindi un nuovo id e un nuovo agent_id, e il vecchio id restituisce 404. L'id di un canale personalizzato dura finché il canale non viene rimosso.

Messaggi diretti di gruppo

Un messaggio diretto di gruppo di Slack ha un ID nel formato di un canale, quindi l'utilizzo di Claude in uno di essi lo configura come un canale: ha un id, viene elencato e può essere letto. Configurarne uno tramite questa API, modificarne un'impostazione e collegarvi un Bundle restituiscono ciascuno 400. Scollegare un Bundle da uno di essi è consentito.

Flussi di lavoro di esempio

Attivare Claude solo nei canali approvati

Qualsiasi membro può invitare Claude in un canale pubblico. Per mantenere Claude attivo solo dove lo hai approvato:

1. Disattiva Claude ovunque impostando enabled su false nei valori predefiniti Slack.
2. Quando il tuo sistema di approvazione approva un canale, configura il canale con "settings": {"enabled": true}. La richiesta accetta gli ID propri di Slack e restituisce il canale indipendentemente dal fatto che fosse già configurato, quindi è sicura da ripetere.
3. Nella stessa esecuzione, collega i Bundle per cui il team è stato approvato, in modo che la prima sessione del canale abbia già i suoi strumenti.

Mantenere la configurazione sotto controllo di versione

1. Indicizza la tua configurazione in base agli ID che Slack mostra per ogni canale, e trova ogni canale tramite essi.
2. Confronta la vista memorizzata con ciò che dichiara il tuo repository. La vista effettiva includerebbe i valori ereditati.
3. Invia solo le impostazioni che differiscono, e invia null per un'impostazione che il tuo repository non dichiara più.
4. Chiedi a un proprietario dell'organizzazione di attivare la modalità di sola lettura, in modo che nessuno modifichi manualmente le stesse impostazioni.

Verificare cosa si applica ovunque

1. Elenca i tuoi workspace, poi elenca i canali di ogni workspace.
2. Leggi le impostazioni effettive di ogni canale e segnala ciò che la tua policy vieta, come un canale in cui enabled è true senza un'approvazione registrata, o in cui guest_policy è allow.
3. Elenca i tuoi Bundle, poi i target di ogni Bundle, per vedere dove è collegato l'accesso a sistemi sensibili.

Canali Slack

L'oggetto canale è la vista memorizzata di un canale Slack:

Un id privo del prefisso slch_ restituisce 400. Un id che ha il prefisso ma non identifica alcun canale della tua organizzazione restituisce 404.

Configurare un canale

POST /v1/organizations/claude_tag/slack_channels configura un canale Slack e lo restituisce. slack.team_id e slack.channel_id sono obbligatori e sono gli ID propri di Slack. settings è facoltativo e segue Modificare le impostazioni. Se il canale è già configurato, la richiesta restituisce il canale esistente e applica settings; la risposta è 200 in entrambi i casi. Richiede lo scope write:claude_tag.

client = anthropic.Anthropic()

channel = client.beta.organization.claude_tag.slack_channels.create(
    slack={"team_id": "T01ABCD2EFG", "channel_id": "C05HJKL6MNP"},
    settings={"instructions": "Answer in the language of the question."},
)

print(channel.id)

{
  "type": "slack_channel",
  "id": "slch_011CZkZmRt4vNq8sHbYw2KdX",
  "slack": {
    "team_id": "T01ABCD2EFG",
    "channel_id": "C05HJKL6MNP"
  },
  "settings": {
    "enabled": null,
    "instructions": "Answer in the language of the question.",
    "model": null,
    "environment_id": null,
    "guest_policy": null
  },
  "agent_id": "cagt_011CZkZsHz6bTh2vNmEu4QrX",
  "created_at": "2026-10-19T16:20:05Z",
  "updated_at": "2026-10-19T16:20:05Z"
}

Prima che un canale venga configurato, l'app Slack di Claude verifica con Slack che il canale si trovi nel workspace, non sia archiviato e sia visibile all'app. Un canale che non supera questa verifica restituisce 404, così come un workspace in cui non è installata l'app Slack di Claude.

Configurare il canale e applicare settings sono due passaggi. Quando il primo riesce e il secondo viene rifiutato, la risposta è il rifiuto e il canale resta configurato senza nulla di memorizzato. Quel rifiuto contiene un error_code che inizia con slack_channel_set_up_ e l'id del nuovo canale in error.details.slack_channel_id (consulta Risposte di errore). Correggi settings e invialo in un aggiornamento a quell'id, oppure invia di nuovo la richiesta di configurazione.

Elencare i canali

GET /v1/organizations/claude_tag/slack_channels elenca i canali configurati di un workspace, dal più recente per created_at. slack_team_id è obbligatorio ed è l'ID proprio di Slack per il workspace. Una pagina può contenere meno di limit canali, o nessuno, mentre next_page è ancora impostato, quindi continua a richiedere pagine finché next_page non è null (consulta Paginazione). Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

channels = client.beta.organization.claude_tag.slack_channels.list(
    slack_team_id="T01ABCD2EFG"
)

# Recupera automaticamente altre pagine quando necessario.
for channel in channels:
    print(f"{channel.id}: {channel.slack.channel_id}")

La risposta è {"data": [...], "next_page": ...}, dove ogni elemento è un oggetto canale. Uno slack_team_id che indica un workspace non posseduto dalla tua organizzazione restituisce 404.

Trovare un canale tramite i suoi ID Slack

Aggiungi slack_channel_id, l'ID proprio di Slack per il canale, per cercare un singolo canale. data contiene quel canale, oppure è vuoto quando il canale non è configurato. Una ricerca ignora limit e page, e il suo next_page è null. È così che trovi l'id di un canale.

client = anthropic.Anthropic()

page = client.beta.organization.claude_tag.slack_channels.list(
    slack_team_id="T01ABCD2EFG",
    slack_channel_id="C05HJKL6MNP",
)

for channel in page.data:
    print(channel.id)

Passare un ID slch_ come slack_channel_id restituisce 400.

Ottenere un canale

GET /v1/organizations/claude_tag/slack_channels/{id} restituisce l'oggetto canale. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

channel = client.beta.organization.claude_tag.slack_channels.retrieve(
    "slch_011CZkZmRt4vNq8sHbYw2KdX"
)

print(channel.settings.enabled)

Aggiornare un canale

POST /v1/organizations/claude_tag/slack_channels/{id} modifica le impostazioni del canale e restituisce l'oggetto canale. settings è obbligatorio e segue Modificare le impostazioni. Richiede lo scope write:claude_tag.

Disattiva Claude in un canale e lascia le sue altre impostazioni come sono:

client = anthropic.Anthropic()

channel = client.beta.organization.claude_tag.slack_channels.update(
    "slch_011CZkZmRt4vNq8sHbYw2KdX",
    settings={"enabled": False},
)

print(channel.settings.enabled)

Cancella le istruzioni del canale, in modo che si applichino solo quelle ereditate:

client = anthropic.Anthropic()

channel = client.beta.organization.claude_tag.slack_channels.update(
    "slch_011CZkZmRt4vNq8sHbYw2KdX",
    settings={"instructions": None},
)

print(channel.settings.instructions)

Ottenere le impostazioni effettive di un canale

GET /v1/organizations/claude_tag/slack_channels/{id}/effective restituisce ciò che si applica nel canale e da dove proviene ciascun valore. Impostazioni memorizzate ed effettive mostra una risposta completa. In questa vista enabled e guest_policy non sono mai null. La vista viene risolta a ogni lettura, quindi non ha created_at né updated_at. Se un livello non può essere letto, la richiesta fallisce con 503 anziché risolvere senza di esso. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

effective = client.beta.organization.claude_tag.slack_channels.effective.retrieve(
    "slch_011CZkZmRt4vNq8sHbYw2KdX"
)

print(effective.settings.instructions)

Rimuovere un canale

DELETE /v1/organizations/claude_tag/slack_channels/{id} rimuove un canale da Claude Tag. È la stessa rimozione che un proprietario dell'organizzazione effettua in claude.ai, con lo stesso effetto. Non elimina, archivia né modifica il canale in Slack, né alcun messaggio al suo interno. Richiede lo scope write:claude_tag.

client = anthropic.Anthropic()

deleted_channel = client.beta.organization.claude_tag.slack_channels.delete(
    "slch_011CZkZmRt4vNq8sHbYw2KdX"
)

print(deleted_channel.id)

{
  "type": "slack_channel_deleted",
  "id": "slch_011CZkZmRt4vNq8sHbYw2KdX"
}

L'id restituisce 404 non appena la richiesta ritorna, e il resto viene eliminato in background. Una rimozione ripetuta restituisce 404.

Rimuovere un canale non impedisce a Claude di operare al suo interno. Claude continua a rispondere secondo ciò che il canale eredita, senza memoria del canale, e il suo utilizzo successivo può configurare di nuovo il canale con un nuovo id.

• Per impedire a Claude di rispondere in un canale, imposta invece enabled su false per quel canale.
• Per fare in modo che un canale non memorizzi nulla e mantenga le sue sessioni e la sua memoria, cancella invece ogni impostazione e scollega ogni Bundle.

Due tipi di canale non possono essere rimossi qui e restituiscono 400: uno che non è personalizzato (error_code: "slack_channel_not_configured"), e uno che contiene una configurazione che questa API non gestisce, come un pool di runner o un'impostazione presente solo in claude.ai. Un proprietario dell'organizzazione rimuove il secondo tipo in claude.ai.

Workspace Slack

L'oggetto workspace è la vista memorizzata di un workspace Slack. Ha gli stessi campi dell'oggetto canale, tranne per il fatto che type è slack_workspace, id ha il prefisso slws_ e slack contiene solo team_id. La risposta dell'Avvio rapido ne mostra uno completo.

Un id privo del prefisso slws_ restituisce 400. Un id che ha il prefisso ma non identifica alcun workspace della tua organizzazione restituisce 404.

Elencare i workspace

GET /v1/organizations/claude_tag/slack_workspaces elenca i workspace configurati che la tua organizzazione possiede, dal più recente per created_at. L'Avvio rapido mostra la richiesta e la risposta. Per trovare un workspace tramite l'ID proprio di Slack, aggiungi slack_team_id: data contiene quel workspace, oppure è vuoto quando non è configurato, e un workspace che la tua organizzazione non possiede restituisce 404. Richiede lo scope read:claude_tag.

Ottenere un workspace

GET /v1/organizations/claude_tag/slack_workspaces/{id} restituisce l'oggetto workspace. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

workspace = client.beta.organization.claude_tag.slack_workspaces.retrieve(
    "slws_011CZkZnWa7xPc3uJfZe5LgT"
)

print(workspace.settings.instructions)

Aggiornare un workspace

POST /v1/organizations/claude_tag/slack_workspaces/{id} modifica le impostazioni del workspace e restituisce l'oggetto workspace. settings è obbligatorio e segue Modificare le impostazioni. Ciò che imposti qui si applica in ogni canale del workspace che non imposta un proprio valore. Richiede lo scope write:claude_tag.

client = anthropic.Anthropic()

workspace = client.beta.organization.claude_tag.slack_workspaces.update(
    "slws_011CZkZnWa7xPc3uJfZe5LgT",
    settings={"guest_policy": {"type": "restrict"}},
)

print(workspace.settings.guest_policy)

Ottenere le impostazioni effettive di un workspace

GET /v1/organizations/claude_tag/slack_workspaces/{id}/effective restituisce ciò che si applica nel workspace, risolto a partire dal workspace e dai valori predefiniti Slack, nella forma mostrata in Impostazioni memorizzate ed effettive, con type impostato su slack_workspace_effective. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

effective = client.beta.organization.claude_tag.slack_workspaces.effective.retrieve(
    "slws_011CZkZnWa7xPc3uJfZe5LgT"
)

print(effective.settings.enabled)

Valori predefiniti Slack

La tua organizzazione ha esattamente un oggetto di valori predefiniti Slack. Si applica a ogni workspace e canale, non ha id e non ha una vista effettiva, poiché non esiste un livello più ampio.

Ottenere i valori predefiniti Slack

GET /v1/organizations/claude_tag/slack_defaults restituisce l'oggetto. Un'organizzazione i cui valori predefiniti Slack non sono configurati riceve 200 con ogni impostazione e agent_id a null. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

defaults = client.beta.organization.claude_tag.slack_defaults.retrieve()

print(defaults.settings.guest_policy)

Aggiornare i valori predefiniti Slack

POST /v1/organizations/claude_tag/slack_defaults modifica i valori predefiniti e restituisce l'oggetto. settings è obbligatorio e segue Modificare le impostazioni. Una richiesta che imposta un valore mentre i valori predefiniti Slack non sono configurati restituisce 400. Richiede lo scope write:claude_tag.

client = anthropic.Anthropic()

defaults = client.beta.organization.claude_tag.slack_defaults.update(
    settings={
        "instructions": "Keep replies under 200 words.",
        "environment_id": "env_011CZkZqDx2zRf5tLjCs7NpV",
    },
)

print(defaults.settings.environment_id)

{
  "type": "slack_defaults",
  "settings": {
    "enabled": null,
    "instructions": "Keep replies under 200 words.",
    "model": null,
    "environment_id": "env_011CZkZqDx2zRf5tLjCs7NpV",
    "guest_policy": null
  },
  "agent_id": "cagt_011CZkZtKa8cUj4wPnFv6RsY"
}

Bundle

Un Bundle è ciò che claude.ai chiama Access bundle: un insieme denominato di accessi, come connettori, repository e credenziali, che Claude può utilizzare in un canale o in un workspace. I proprietari dell'organizzazione creano, modificano ed eliminano i Bundle in claude.ai. Questa API li elenca e li collega. Restituisce il nome e la descrizione di un Bundle e mai ciò che il Bundle concede.

Un bundle_id privo del prefisso capp_ restituisce 400. Uno che ha il prefisso ma non esiste o appartiene a un'altra organizzazione restituisce 404, indipendentemente da cos'altro contenga la richiesta. I Bundle che Claude Tag gestisce per sé non vengono elencati e restituiscono 404.

Elencare i Bundle

GET /v1/organizations/claude_tag/bundles elenca i Bundle della tua organizzazione, dal più recente per created_at. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

bundles = client.beta.organization.claude_tag.bundles.list()

# Recupera automaticamente altre pagine quando necessario.
for bundle in bundles:
    print(f"{bundle.id}: {bundle.display_name}")

{
  "data": [
    {
      "type": "bundle",
      "id": "capp_011CZkZjLP1cWxj5EtMmdgbq",
      "display_name": "Support tools",
      "description": "Issue tracker and the support runbooks repository.",
      "created_at": "2026-09-12T08:15:30Z",
      "updated_at": "2026-09-30T13:02:47Z"
    }
  ],
  "next_page": null
}

Ottenere un Bundle

GET /v1/organizations/claude_tag/bundles/{bundle_id} restituisce l'oggetto Bundle. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

bundle = client.beta.organization.claude_tag.bundles.retrieve(
    "capp_011CZkZjLP1cWxj5EtMmdgbq"
)

print(bundle.display_name)

Bundle target

Un Bundle target è il record di un Bundle collegato a un canale o a un workspace. Un Bundle collegato a un workspace può essere utilizzato nel workspace e in ogni canale al suo interno. Un Bundle collegato a un canale può essere utilizzato solo in quel canale.

Un Bundle viene collegato a un canale o a un workspace al massimo una volta, e la stessa coppia ha sempre lo stesso id, anche dopo uno scollegamento e un nuovo collegamento. L'id è opaco: ottienilo dalla risposta a un collegamento o dall'elenco. Un Bundle target non contiene l'id del suo Bundle, che è necessario anche nei suoi percorsi, quindi conserva i due insieme.

Il primo Bundle collegato a un canale o a un workspace lo rende personalizzato. Collegare o scollegare non modifica alcuna impostazione memorizzata. Le sessioni in esecuzione nel canale o nel workspace vengono informate che il suo accesso è cambiato.

Il Bundle che claude.ai collega come parte di una configurazione di reperibilità (on-call) viene elencato e può essere letto, ma non può essere collegato o scollegato qui, e nulla può essere collegato a un canale o workspace gestito da una configurazione di reperibilità, né scollegato da esso. Ciascuna di queste richieste restituisce 400.

Elencare i target di un Bundle

GET /v1/organizations/claude_tag/bundles/{bundle_id}/targets elenca i canali e i workspace a cui il Bundle è collegato, dal più recente per created_at. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

targets = client.beta.organization.claude_tag.bundles.targets.list(
    "capp_011CZkZjLP1cWxj5EtMmdgbq"
)

# Recupera automaticamente altre pagine quando necessario.
for target in targets:
    print(f"{target.id}: {target.type}")

{
  "data": [
    {
      "type": "slack_channel",
      "id": "btgt_011CZkZpBv9yQd6wKhAr8MnU",
      "slack_channel_id": "slch_011CZkZmRt4vNq8sHbYw2KdX",
      "created_at": "2026-10-19T16:21:44Z"
    },
    {
      "type": "slack_workspace",
      "id": "btgt_011CZkZuMc3dVk7xQpGw9StZ",
      "slack_workspace_id": "slws_011CZkZnWa7xPc3uJfZe5LgT",
      "created_at": "2026-09-12T08:17:02Z"
    }
  ],
  "next_page": null
}

Vengono elencati solo i collegamenti a canali e workspace. Un Bundle collegato in claude.ai a qualcos'altro, come Default Slack access, non ha un Bundle target corrispondente, e lo stesso vale per una regola che applica un Bundle in molti canali contemporaneamente. Quindi i Bundle che Claude può utilizzare in un canale possono essere più dei target che lo nominano. Nessun endpoint elenca i Bundle collegati a un singolo canale o workspace.

Collegare un Bundle

POST /v1/organizations/claude_tag/bundles/{bundle_id}/targets collega il Bundle e restituisce il Bundle target. Il corpo indica il type e l'id corrispondente. Il canale o il workspace deve essere già configurato: il collegamento non configura mai un canale. Collegare una coppia già collegata restituisce 200 con il Bundle target esistente. Richiede lo scope write:claude_tag.

Collega un Bundle a un canale:

client = anthropic.Anthropic()

target = client.beta.organization.claude_tag.bundles.targets.create(
    "capp_011CZkZjLP1cWxj5EtMmdgbq",
    type="slack_channel",
    slack_channel_id="slch_011CZkZmRt4vNq8sHbYw2KdX",
)

print(target.id)

{
  "type": "slack_channel",
  "id": "btgt_011CZkZpBv9yQd6wKhAr8MnU",
  "slack_channel_id": "slch_011CZkZmRt4vNq8sHbYw2KdX",
  "created_at": "2026-10-19T16:21:44Z"
}

Collega un Bundle a un workspace:

client = anthropic.Anthropic()

target = client.beta.organization.claude_tag.bundles.targets.create(
    "capp_011CZkZjLP1cWxj5EtMmdgbq",
    type="slack_workspace",
    slack_workspace_id="slws_011CZkZnWa7xPc3uJfZe5LgT",
)

print(target.id)

Un collegamento a un canale ha delle condizioni in base alle quali si applica, ad esempio solo finché nel canale non è presente alcun ospite Slack. Le condizioni vengono impostate in claude.ai e non vengono restituite qui. Il collegamento tramite questa API utilizza le condizioni predefinite, e collegare una coppia già collegata lascia invariate le sue condizioni.

Ottenere un Bundle target

GET /v1/organizations/claude_tag/bundles/{bundle_id}/targets/{target_id} restituisce il Bundle target. Un target_id privo del prefisso btgt_ restituisce 400. Uno che appartiene a un altro Bundle, è stato scollegato o identifica un canale o workspace non più configurato restituisce 404. Richiede lo scope read:claude_tag.

client = anthropic.Anthropic()

target = client.beta.organization.claude_tag.bundles.targets.retrieve(
    "btgt_011CZkZpBv9yQd6wKhAr8MnU",
    bundle_id="capp_011CZkZjLP1cWxj5EtMmdgbq",
)

print(target.type)

Scollegare un Bundle

DELETE /v1/organizations/claude_tag/bundles/{bundle_id}/targets/{target_id} scollega il Bundle. Uno scollegamento ripetuto restituisce 404. Richiede lo scope write:claude_tag.

client = anthropic.Anthropic()

deleted_target = client.beta.organization.claude_tag.bundles.targets.delete(
    "btgt_011CZkZpBv9yQd6wKhAr8MnU",
    bundle_id="capp_011CZkZjLP1cWxj5EtMmdgbq",
)

print(deleted_target.id)

{
  "type": "bundle_target_deleted",
  "id": "btgt_011CZkZpBv9yQd6wKhAr8MnU"
}

Valori non riconosciuti

guest_policy.type, il type di una fonte, il type di un Bundle target e i codici di errore possono acquisire nuovi valori in qualsiasi momento. Tratta un valore che non riconosci come faresti con qualsiasi stringa sconosciuta, anziché generare un errore.

Limitazione della velocità

Le richieste sono soggette a un "rate limit" (limite di velocità) per organizzazione, in due budget condivisi da tutte le chiavi della tua organizzazione e separati dagli altri limiti dell'Admin API della tua organizzazione. Ogni budget consente una raffica di richieste e poi si ricarica a un ritmo costante:

Le richieste che superano un budget restituiscono 429 Too Many Requests con un header retry-after. Le risposte includono gli header anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining e anthropic-ratelimit-requests-reset per il budget da cui la richiesta ha attinto.

Paginazione

Gli endpoint di elenco utilizzano un "opaque cursor" (cursore opaco). La prima richiesta restituisce fino a limit righe più un cursore next_page; passa il cursore invariato come parametro page nella richiesta successiva e ripeti finché next_page non è null. Tratta la stringa del cursore come opaca: non analizzarla, modificarla o costruirla tu stesso. Elencare i canali può restituire una pagina con meno di limit canali, o nessuno, mentre next_page è ancora impostato, quindi continua a richiedere pagine finché next_page non è null. Gli iteratori di elenco degli SDK Python, TypeScript, C#, Go, Java e Ruby e la CLI (tranne con --format raw) lo fanno per te. In PHP e curl, richiedi ogni pagina tu stesso e passa il suo next_page come page.

limit ha come valore predefinito 20, con un minimo di 1 e un massimo di 100. Ogni elenco è ordinato dal più recente per created_at e non accetta altri ordinamenti.

Risposte di errore

Le risposte di errore seguono la forma standard documentata in Errori. Cita il request_id dal corpo della risposta quando contatti il supporto.

Quando uno stato ha diverse cause che gestiresti in modo diverso, l'errore contiene anche error.details.error_code:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "...",
    "details": {
      "error_code": "slack_channel_set_up_settings_refused",
      "slack_channel_id": "slch_011CZkZmRt4vNq8sHbYw2KdX"
    }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

Potrebbero essere aggiunti nuovi codici. Tratta un codice che non riconosci nel modo in cui tratti il suo stato. Un 404 senza error_code ha una di due cause. O qualcosa che la richiesta nomina non è stato trovato (un id nel percorso, oppure un canale o workspace Slack nel corpo o nella query), oppure ogni endpoint risulta inesistente perché la richiesta omette il valore anthropic-beta o l'API non è abilitata per la tua organizzazione. Per distinguerle, ottieni i valori predefiniti Slack con la stessa chiave e gli stessi header: quella richiesta non nomina nulla, quindi restituisce 404 solo nel secondo caso.

Eventi dell'Activity Feed

Ogni modifica effettuata tramite questa API viene registrata nel Compliance API Activity Feed della tua organizzazione, attribuita alla chiave API come api_actor con il relativo ID apikey_. Gli eventi sono gli stessi che il feed registra quando la stessa modifica viene effettuata in claude.ai, quindi un'unica query trova una modifica indipendentemente dal modo in cui è stata effettuata.

Gli eventi identificano un canale o un workspace tramite il suo agent_id, non tramite il suo id. I due eventi Bundle identificano il Bundle in profile_id e il canale o il workspace in scope_id.

Un evento ccr_agent_updated elenca ciò che è cambiato in updated_fields, con i nomi propri del feed:

Le letture, le richieste che non modificano nulla e le richieste rifiutate prima che venga memorizzato qualcosa non registrano nulla. Una richiesta di configurazione che configura un canale e il cui settings viene poi rifiutato registra ccr_agent_created.

Vedi anche