> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors per prompt

> Choose exactly which connections a project prompt may use, narrow their actions, and start new connections.

Each project prompt can choose **which connected services** the agent may use and **which of their actions** are allowed. These settings only narrow what the connection already allows. They never change workspace, organization or connection settings.

## Available services and connected accounts

**List connectors** (`GET /connectors`, MCP `list_connectors`) shows what you can connect: GitHub, Notion, Google Drive, Getty Images and S3, plus YouTube, Instagram, TikTok, Facebook, X, Threads, LinkedIn, Reddit, Mastodon, Bluesky and Snapchat. Each option has a service `id`, an authentication method, an `input_schema` and setup availability. Check `available` before starting setup.

**List connections** (`GET /connections`, MCP `list_connections`) shows the accounts you already connected. Every connection belongs to your API credential’s **organization and workspace** and is **private to the member who connected it**. Other members cannot list, read, use or delete it. Shared connection management can come later; the app’s existing shared connections keep their current behavior. Social connections use the same IDs in project prompts and [Social posting](https://docs.motion.so/product/social-posting.md).

The two IDs have different purposes:

| Field | Example | Use |
| - | - | - |
| Catalog `id` / `connector_id` | `github` | Choose which service to connect. |
| Connection `id` | `6f1c0c1e-2b8a-4c55-9a51-0b6c1f0f7d10` | Choose the exact saved account a project may use. |

Connection `status` is `connected`, `unverified` or `needs_attention`. `verified_at` is the time of its last check. Read `GET /connections/{connection_id}` (MCP `get_connection`) to inspect it. Google Drive and social status reads reconcile OAuth completion. A disconnected account returns 404.

`permission_options` lists the action IDs a provider supports. `capabilities` says which are currently allowed for this account. Copy allowed `permission_options[].id` values into a project's `actions`; these are permission groups, not raw tool names.

## Choose connections for a prompt

Send `connectors` with `POST /projects` or `POST /projects/{project_id}/messages` (MCP: `create_project`, `send_project_message`):

```json theme={null}
{
  "prompt": "Make a launch video from our release notes",
  "connectors": [
    { "id": "6f1c0c1e-2b8a-4c55-9a51-0b6c1f0f7d10", "actions": ["repositories", "code"] },
    { "id": "1d2e3f40-5a6b-4c7d-8e9f-a0b1c2d3e4f5" }
  ]
}
```

| Value | Meaning |
| - | - |
| Omitted | Keep the project's current connector choice. |
| An array | Use only these connections, for this message and later ones. |
| `[]` | Turn off all connectors. |

* `id` is a connection `id` from `GET /connections`. The project uses that exact account; Motion never picks another account of the same provider.
* Choose at most one connection per provider. A project keeps the account it first used for a provider. To use a different account of that provider, start a new project.
* `actions` is optional. It must be a subset of that connection's `permission_options` ids that are currently allowed in `capabilities`. Omit it to keep the connection's current actions.
* Choosing connections requires `motion:sessions:write` **and** `motion:connectors:read` for your private connections in this organization workspace. Turning connectors off with `[]` only needs `motion:sessions:write`.

### Actions by provider

| Provider | `actions` |
| - | - |
| GitHub | `repositories`, `code`, `issues`, `history` |
| Notion | `pages`, `comments`, `create_pages`, `edit_pages`, `add_comments` |
| Google Drive | `files`, `downloads`, `uploads`, `folders` |
| S3 | `files`, `downloads`, `uploads`, `deletes` |
| Getty Images | `search`, `downloads` |
| Social platforms | `posts` (read), `prepare` (propose posts for approval), `discard` (cancel pending proposals) |

Social actions never bypass posting approval. `prepare` creates a proposal. A private account’s creator must approve it in Socials while they are a workspace manager. Shared accounts require a workspace manager’s approval. Connection permissions enable all three social actions; each prompt can narrow them.

Read a project to inspect its current `connectors`. `null` means no explicit selection, `[]` disables all connectors, and `actions: null` keeps the connection's current allowed actions.

## While the agent is working

Turning a connector off or narrowing actions while a turn is running takes effect at its **next** connector call. A newly enabled provider may become available on the next turn, when its tools connect. A turned-off connection, or an action outside the selection, is refused when the agent tries to use it.

Every connector call also checks the live connection, workspace, organization and attached template/brand-kit restrictions. A template that prohibits a connection makes it unavailable even when the prompt explicitly selected it. If an admin later restricts an action, that restriction applies even when a prompt selected it.

## Errors

| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | Unknown action, duplicate ID, or two connections of one provider. |
| 400 | `connector_unsupported` | This provider cannot be used by projects. |
| 403 | Missing scope | The key lacks `motion:connectors:read`. |
| 403 | `connector_disabled` | Agent permissions turn this connection off. |
| 403 | `connector_action_unavailable` | An action is not currently allowed for this connection. |
| 404 | `connector_not_found` | The ID is not available to this key. |
| 409 | `connector_conflict` | The project already uses another account of that provider. |

A rejected request does not create a project or send a message.

## Connect a service

Organization owners/admins and workspace members can connect tool services. Social account setup currently requires a workspace manager. Organization/workspace policies and product rollout restrictions still apply. The API never changes the credential’s workspace or shares a new connection.

`POST /connections` (MCP `connect_service`) takes `connector_id` from the catalog and that option's setup inputs. It needs `motion:connectors:write` and the organization member access reported by the catalog.

### OAuth

```json theme={null}
{ "connector_id": "google-drive" }
```

The response contains `status: "pending_authorization"`, an `authorization_url`, `expires_at` (when known) and `connections_url`. A person must open the link and approve access. Poll `connections_url` to find the saved connection's UUID. Requesting a link or cancelling approval creates no connected account. Social setup accepts an optional `name` and `request_id`. Reuse the ID for retries; a completed request returns the saved connection. If an uncertain provider failure returns 409, start a fresh request ID.

GitHub, Notion, Google Drive and the listed social platforms use their existing product authorization flows. Provider configuration, account access and rollout restrictions apply; check the catalog's `available` field first.

### Credentials

Getty Images accepts its API key and client secret:

```json theme={null}
{
  "connector_id": "getty",
  "credentials": { "api_key": "YOUR_GETTY_KEY", "client_secret": "YOUR_GETTY_SECRET" }
}
```

S3 accepts AWS credentials and a bucket configuration:

```json theme={null}
{
  "connector_id": "s3",
  "credentials": { "access_key_id": "AKIAEXAMPLE00000000", "secret_access_key": "YOUR_AWS_SECRET_ACCESS_KEY" },
  "config": { "bucket": "acme-media", "region": "us-east-1", "prefix": "motion/", "read_test_key": "motion/existing-video.mp4" },
  "actions": ["files", "downloads"]
}
```

S3 `actions` are `files`, `downloads`, `uploads` and `deletes`. The default is read-only `files` and `downloads`; read-only setup requires an existing nonempty `read_test_key` inside `prefix`. Optional `credentials.session_token` supports temporary AWS credentials. Motion verifies the requested AWS permissions before saving the connection. Bucket, region and prefix must pass the same constraints as the app; consult the catalog's `input_schema` for field limits.

Successful credential setup returns `status: "connected"` and the saved `connection`. Credentials are encrypted at rest and never included in list, read or project responses.

## Disconnect

`DELETE /connections/{connection_id}` (MCP `delete_connection`) disconnects your private organization connection. Motion disconnects the account and revokes provider access where supported. Credential-based providers have no OAuth grant to revoke. Tool-service revocation failures retain the account for retry. Social disconnect disables local access immediately, even if the provider cannot confirm unlinking. Disconnecting a private social account cancels its pending posts that have not been submitted to the provider. Posts already submitted remain in reconciliation. Projects cannot use a deleted connection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.