Create a connector

Creates a connector. The request body is discriminated on provider.

OAuth/app providers (google_sheets, github, slack) — supply { provider, name, events }. The connector is created enabled: false with empty config and no credentials; the provider's OAuth flow then attaches credentials and enables it.
Trigger providers (claude_trigger, cursor_trigger, copilot_trigger, jules_trigger) — supply config plus the provider's credential field(s) and the connector is fireable immediately. Trigger creates are idempotent by their natural key (config.routineId / config.repoUrl / config.owner+config.repo / config.source): re-creating updates the existing row rather than duplicating it.

Use cases

File bugs as GitHub Issues — { "provider": "github", "name": "Bugs → acme/app", "events": ["bug.created"] }, then finish the GitHub App install.
Nightly ops sweep — register a claude_trigger with its routineId and (optionally) a fire token; subscribe events later to auto-fire on new bugs.
Cold cloud-agent run — register a cursor_trigger/jules_trigger with the repo coordinates plus both keys, or a copilot_trigger with the repo + user PAT.

Authorization

bearerSdkKey

AuthorizationBearer <token>

Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".

In: header

Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

provider*string

OAuth/app connector destination.

Value in"google_sheets" | "github" | "slack"

name*string

Human-readable connector label.

Length1 <= length <= 80

events*array<>

Events to subscribe to. At least one is required.

Items1 <= items

provider*string

Discriminator. Claude Code scheduled-routine trigger.

Value in"claude_trigger"

name?string

Human-readable connector label.

Default"Claude trigger"

Length1 <= length <= 80

events?array<>

Events that auto-fire the routine. Defaults to empty so the trigger does not auto-fire paid runs until events are subscribed.

Default[]

config*

Non-secret config for a Claude trigger.

token?string

The routine's fire bearer token (secret). Optional — a tokenless trigger is recorded but not fireable until a token is added later. Encrypted into the credentials cipher; never persisted in config or returned.

Length1 <= length

enabled?boolean

Whether the trigger is active on create.

Defaulttrue

provider*string

Discriminator. Cursor cloud-agent trigger.

Value in"cursor_trigger"

name?string

Human-readable connector label.

Default"Cursor trigger"

Length1 <= length <= 80

events?array<>

Events that auto-fire a cold cloud-agent run. Defaults to empty.

Default[]

config*

Non-secret config for a Cursor trigger.

apiKey*string

Cursor API key that launches the run (secret). Encrypted into the credentials cipher; never returned.

Length1 <= length

opsKey*string

Restricted Shipeasy ops key, injected into the run as SHIPEASY_CLI_TOKEN via the launch envVars (secret). Encrypted; never returned.

Length1 <= length

enabled?boolean

Whether the trigger is active on create.

Defaulttrue

provider*string

Discriminator. GitHub Copilot coding-agent trigger.

Value in"copilot_trigger"

name?string

Human-readable connector label.

Default"Copilot trigger"

Length1 <= length <= 80

events?array<>

Events that auto-fire a Copilot agent task. Defaults to empty.

Default[]

config*

Non-secret config for a Copilot trigger.

token*string

Copilot-licensed user PAT (secret). The ops key lives in the repo's GitHub "Agents" secret store and is never sent through Shipeasy. Encrypted; never returned.

Length1 <= length

enabled?boolean

Whether the trigger is active on create.

Defaulttrue

provider*string

Discriminator. Google Jules trigger.

Value in"jules_trigger"

name?string

Human-readable connector label.

Default"Jules trigger"

Length1 <= length <= 80

events?array<>

Events that auto-fire a Jules session. Defaults to empty.

Default[]

config*

Non-secret config for a Jules trigger.

apiKey*string

Jules API key that launches the session (secret). Encrypted into the credentials cipher; never returned.

Length1 <= length

opsKey*string

Restricted Shipeasy ops key, embedded in the prompt (Jules exposes no env channel) (secret). Encrypted; never returned.

Length1 <= length

enabled?boolean

Whether the trigger is active on create.

Defaulttrue

Response Body

`application/json`

curl -X POST "https://shipeasy.ai/api/admin/connectors" \  -H "Content-Type: application/json" \  -d '{    "provider": "github",    "name": "Bugs → acme/app issues",    "events": [      "bug.created"    ]  }'

{
  "id": "9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10"
}

{
  "error": "Malformed request (bad JSON, missing project scope).",
  "code": "BAD_REQUEST"
}

{
  "error": "Missing or invalid admin SDK key.",
  "code": "UNAUTHORIZED"
}

{
  "error": "Key is valid but not allowed to act on this project.",
  "code": "FORBIDDEN"
}

{
  "error": "The resource does not exist or is not visible to the caller.",
  "code": "NOT_FOUND"
}

{
  "error": "A resource with this name already exists in the project.",
  "code": "ALREADY_EXISTS"
}

{
  "error": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?

✎ Edit this page

Create a connector

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

Not an admin of this project

Feature gated behind a higher plan

Duplicate name

Still referenced by another resource

Illegal lifecycle transition

Edited an immutable field while running

Schema validation failed

Referenced entity missing

Group weights must sum to 10000

Event still pending review

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`