Connectors API

{
  ok: true
  connectors: Array<{
    connectorId: string
    slug: string
    toolCount: number
    tools: string[] // tool names, each prefixed with the slug
    skipped: Array<{ name: string; reason: string }>
    specHash: string
    toolsHash: string
  }>
}

curl http://localhost:18790/api/connectors

{ ok: true; slugs: string[]; supplied: string[] }

curl http://localhost:18790/api/connectors/configured

{
  ok: true
  suggestions: Array<{ label: string; path: string }>
}

{ "error": "that connector does not take a path" }

curl "http://localhost:18790/api/connectors/path-suggestions?slug=filesystem"

{
  slug: string // 1 to 48 characters, lowercase letters, digits and dashes, starting with a letter or digit
}

{
  ok: true
  connectorId: string
  command: string // the command that actually ran, or the URL of a remote connector
  tools: string[]
  skipped: Array<{ name: string; reason: string }>
}

{ "error": "no catalog connector named <slug>" }

{ "error": "Sign in to this provider to connect it.", "reason": "remote-needs-oauth" }

{
  error: string
  detail: string
}

curl -X POST http://localhost:18790/api/connectors/connect \
  -H 'Content-Type: application/json' \
  -d '{"slug":"filesystem"}'

{ "error": "connector is not connected" }

curl -X POST http://localhost:18790/api/connectors/filesystem/disconnect

{
  ok: true
  authorizeUrl: string
}

{ "error": "only remote connectors sign in" }

// the request never left this machine
{
  error: 'Could not reach <Name>. The request did not leave this machine, so this is network rather than the connector.'
}
// anything else, for example a provider without dynamic client registration
{
  error: '<Name> could not start sign-in. <detail>'
} // detail redacted, at most 200 characters

curl -X POST http://localhost:18790/api/connectors/linear/authorize

{
  ok: true
  authorized: true
}

curl -X POST http://localhost:18790/api/connectors/linear/authorize/await

curl -X DELETE http://localhost:18790/api/connectors/linear/authorize

{
  ok: true
  credentials: Array<{
    key: string // the variable name, for example NOTION_TOKEN
    label?: string
    description: string
    required: boolean
    secret: boolean
    present: boolean // a value is stored; the value is never returned
    docsUrl?: string
  }>
  argument: string | null // the stored launch argument; null when none or empty
  argumentSpec: {
    label: string
    description: string
    example: string
    replacesArg?: string
  } | null // null when the connector takes no launch argument
  authorized: boolean
  satisfied: boolean
}

curl http://localhost:18790/api/connectors/filesystem/config

{ "error": "<KEY> is not declared by <slug>" }

curl -X PUT http://localhost:18790/api/connectors/filesystem/config \
  -H 'Content-Type: application/json' \
  -d '{"argument":"/Users/me/projects"}'

curl -X PUT http://localhost:18790/api/connectors/notion/config \
  -H 'Content-Type: application/json' \
  -d '{"values":{"NOTION_TOKEN":"ntn_..."}}'

{ "ok": true, "hasKey": false, "known": true, "connected": [] }

{ ok: true; hasKey: true; known: boolean; connected: string[]; keyRejected: boolean }

{ "error": "Could not read connected apps. <message>" }

curl http://localhost:18790/api/connectors/composio

{
  ok: true
  hasKey: true
  verified: boolean
}

{ "error": "Composio rejected that key. Copy it again from your project settings." }

curl -X PUT http://localhost:18790/api/connectors/composio/key \
  -H 'Content-Type: application/json' \
  -d '{"apiKey":"ak_xxxxxxxxxxxx"}'

curl -X DELETE http://localhost:18790/api/connectors/composio/key

{
  ok: true
  url: string
}

{ "error": "Add a Composio key first.", "reason": "no-key" }

{ "error": "<App name> could not be connected. <detail>" }

curl -X POST http://localhost:18790/api/connectors/composio/apps/gmail/authorize

{
  ok: true
  connectors: Array<{
    slug: string
    displayName: string
    description: string // 'A connector you added.' when none was given
    category: 'dev'
    provenance: 'custom'
    launch: {
      transport: 'stdio'
      command: string
      args: string[]
      pinnedVersion: string // the version you were shown, else 'user-supplied'
    }
    auth:
      | {
          kind: 'api-key'
          inputs: Array<{ key: string; description: string; required: boolean; secret: true }>
        }
      | { kind: 'none'; inputs: [] } // when no authInputs were declared
    egressAllow: ['*']
    trifecta: { readsPrivateData: true; ingestsUntrustedContent: true; canEgress: true } // the three risk flags
    tags: ['custom']
    catalogId?: string
  }>
}

curl http://localhost:18790/api/connectors/custom

{
  ok: true
  slug: string
}

{ "error": "<slug> is already a catalog connector" }

curl -X POST http://localhost:18790/api/connectors/custom \
  -H 'Content-Type: application/json' \
  -d '{
        "slug": "my-notes",
        "displayName": "My Notes",
        "command": "node",
        "args": ["/Users/me/servers/notes/index.js"],
        "authInputs": [{ "key": "NOTES_API_KEY", "description": "Key for the notes server", "required": true }]
      }'

curl -X DELETE http://localhost:18790/api/connectors/custom/my-notes

interface GrantRow {
  id: string
  subjectKind: 'agent' | 'team' | 'global'
  subjectId: string | null // null for 'global'
  capabilityKind: 'connector' | 'tool' | 'skill'
  connectorId: string | null
  capabilityId: string | null
  toolAllow: string[] // tool-name patterns; ['*'] is every tool, [] is none
  toolDeny: string[] // checked first; a denied name is out of scope even if allowed
  mode: 'read' | 'write' | 'admin'
  approvalPolicy: 'never' | 'risk' | 'writes' | 'always'
  state: 'proposed' | 'active' | 'suspended' | 'revoked' | 'expired'
  expiresAt: number | null
  specHashPin: string | null // when set, calls are denied once the connector's spec differs from it
  toolsHashPin: string | null // the same, for the connector's tool list
  callCeilingPerHour: number | null
  origin: 'owner' | 'operator'
  grantedBy: string | null
  grantedAt: number
  revokedAt: number | null
  revokedReason: string | null
}

curl "http://localhost:18790/api/grants?subjectId=<agent-id>"

curl -X POST http://localhost:18790/api/grants \
  -H 'Content-Type: application/json' \
  -d '{"subjectKind":"agent","subjectId":"<agent-id>","capabilityKind":"connector","connectorId":"github","mode":"read","approvalPolicy":"risk"}'

curl -X POST http://localhost:18790/api/grants/<grant-id>/revoke \
  -H 'Content-Type: application/json' \
  -d '{"reason":"detached from the graph"}'

{ "error": "the undo window has closed" }

curl -X POST http://localhost:18790/api/grants/<grant-id>/resume