Logo
Search
Docs

Update connector context

PUT https://app.sulus.ai/api/v1/agents/{agent_id}/connectors/{connector_id}/context

Set per-agent description, purpose, and use case for an enabled connector

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Path parameters

agent_id string Required

The agent id (UUID).

Validation: uuid (route-constrained)
Stored in ai_projects.uid
connector_id string Required

The connector uid from the list response.

Validation: uuid (route-constrained)
Stored in ai_mcp_connectors.uid

Request body

description string Optional Nullable

Agent overlay. Blank or null inherits the connector description.

Validation: sometimes|nullable|string|max:2000
Stored in ai_project_mcp_connectors.description
purpose string Optional Nullable

Agent overlay. Blank or null inherits the connector purpose.

Validation: sometimes|nullable|string|max:2000
Stored in ai_project_mcp_connectors.purpose
use_case string Optional Nullable

Agent overlay. Blank or null inherits the connector use case.

Validation: sometimes|nullable|string|max:2000
Stored in ai_project_mcp_connectors.use_case

Errors

StatusMeaningBody
404 Agent not found, or you do not have access to it
404 Connector not found, inactive, or not available to you
403 You do not have MCP access to this agent. {"message":"You do not have MCP access to this agent."}
422 Connector is not enabled on this agent {"message":"Enable this connector on the agent before editing its context."}
422 Validation failed {"message":"…","errors":{"field":["…"]}}
401 Missing or invalid bearer token
403 Feature ai_chat not enabled for the account

Notes

  • Requires connector permission on the agent (independent of write access). The connector must already be enabled on this agent.
  • Does not rewrite the account connector row. Omitted keys are left unchanged. Blank strings are stored as null and inherit the connector defaults.
  • description, purpose, and use_case in the response are effective values after the save. connector_* fields are the unchanged connector defaults.
curl --request PUT \
  --url https://app.sulus.ai/api/v1/agents/{agent_id}/connectors/{connector_id}/context \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "Use this connector only for this agent'\''s customer lookups.",
  "purpose": "Look up the caller in the customer directory before quoting hours.",
  "use_case": "When the caller asks about their account or a recent order."
}'
import requests

url = "https://app.sulus.ai/api/v1/agents/{agent_id}/connectors/{connector_id}/context"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}
payload = {
  "description": "Use this connector only for this agent's customer lookups.",
  "purpose": "Look up the caller in the customer directory before quoting hours.",
  "use_case": "When the caller asks about their account or a recent order."
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://app.sulus.ai/api/v1/agents/{agent_id}/connectors/{connector_id}/context"
	payload := strings.NewReader(`{
  "description": "Use this connector only for this agent's customer lookups.",
  "purpose": "Look up the caller in the customer directory before quoting hours.",
  "use_case": "When the caller asks about their account or a recent order."
}`)
	req, _ := http.NewRequest("PUT", url, payload)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	req.Header.Add("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
Response 200 
{
    "message": "Connector context updated for this agent.",
    "data": {
        "uid": "c3d4e5f6-0000-4000-8000-000000000030",
        "description": "Use this connector only for this agent's customer lookups.",
        "purpose": "Look up the caller in the customer directory before quoting hours.",
        "use_case": "When the caller asks about their account or a recent order.",
        "connector_description": "Searches the internal knowledge base and returns matching articles.",
        "connector_purpose": "Answer product questions from the knowledge base.",
        "connector_use_case": "When a caller asks how a feature works.",
        "context_overridden": true
    }
}