Retrieve a connector

Fetch a single connector by ID, including the full tools[] surface so you can plan which tools to assign to an agent.

Scope: connectors:read

Path parameters

Example request

curl https://dashboard.getmacha.com/api/v1/connectors/connector_64f1c0ef2ec711ef6dc1dcf \
  -H "Authorization: Bearer $MACHA_API_KEY"

Example response

{
  "data": {
    "id": "connector_64f1c0ef2ec711ef6dc1dcf",
    "type": "zendesk",
    "name": "Production Zendesk",
    "status": "connected",
    "status_reason": null,
    "is_active": true,
    "created_at": "2026-06-01T00:00:00.000Z",
    "updated_at": "2026-06-20T12:00:00.000Z",
    "tools": [
      {
        "name": "zendesk_get_ticket",
        "label": "Get Ticket",
        "description": "Fetch a Zendesk ticket by ID.",
        "type": "read",
        "requires_confirmation": false,
        "disabled": false
      },
      {
        "name": "zendesk_add_public_reply",
        "label": "Add Public Reply",
        "description": "Post a public reply to a ticket. Awaits approval before sending.",
        "type": "write",
        "requires_confirmation": true,
        "disabled": false
      }
    ]
  },
  "meta": { "request_id": "req_..." }
}

Using the tool list

When creating or updating an agent, pass tool refs as { name, connector_id }. The name values come from this endpoint's tools[].name:

// 1. Fetch the connector
const conn = await fetch('https://dashboard.getmacha.com/api/v1/connectors/' + connectorId, {
  headers: { Authorization: `Bearer ${process.env.MACHA_API_KEY}` }
}).then(r => r.json());

// 2. Filter to read-only tools, build refs
const readTools = conn.data.tools
  .filter(t => t.type === 'read' && !t.disabled)
  .map(t => ({ name: t.name, connector_id: conn.data.id }));

// 3. Assign to an agent
await fetch('https://dashboard.getmacha.com/api/v1/agents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MACHA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    handle: 'readOnlyZendesk',
    name: 'Read-only Zendesk',
    instructions: 'Answer questions using Zendesk data. Never modify tickets.',
    tools: readTools,
  }),
});

Errors