> ## 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.

# List connections

> Read your private connections and their available actions. Social authorization completion is reconciled when you poll connections after approving the link.



## OpenAPI

````yaml /openapi.json get /connections
openapi: 3.1.0
info:
  title: Motion
  version: 1.1.0
  description: >-
    Create Motion projects from prompts, read authored generations and outputs,
    and explicitly request renders or editor exports. Use reusable templates and
    brand kits. Credentials remain bound to current workspace access and
    permissions. Legacy single-video endpoints are deprecated.
servers:
  - url: https://api.motion.so/api/motion
security:
  - MotionApiKey: []
tags:
  - name: Projects
  - name: Project results
  - name: Project exports
  - name: Templates
  - name: Brand kits
  - name: Media library
  - name: Automations
  - name: Social posting
  - name: API information
  - name: Deprecated endpoints
    description: >-
      Older single-video routes remain callable for existing clients. Use the
      project API for new integrations; no removal date is scheduled.
  - name: Connectors
    description: Connect services and control the actions a project may use.
paths:
  /connections:
    get:
      tags:
        - Connectors
      summary: List connections
      description: >-
        Read your private connections and their available actions. Social
        authorization completion is reconciled when you poll connections after
        approving the link.
      operationId: ListConnections
      parameters:
        - name: connector_id
          in: query
          description: >-
            Filter by catalog service ID. Omit to list all your private
            organization accounts.
          schema:
            type: string
            enum:
              - github
              - notion
              - figma
              - google-drive
              - dropbox
              - getty
              - s3
              - slack
              - x
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MotionPrivateConnections'
              example:
                connections:
                  - id: 6f1c0c1e-2b8a-4c55-9a51-0b6c1f0f7d10
                    connector_id: github
                    scope: organization
                    name: acme-dev
                    status: connected
                    can_use: true
                    capabilities:
                      repositories: true
                      code: true
                      issues: true
                      history: true
                    permission_options:
                      - id: repositories
                        label: Read repository details
                        write: false
                      - id: code
                        label: Read and search code
                        write: false
                      - id: issues
                        label: Read issues and pull requests
                        write: false
                      - id: history
                        label: Read commits and releases
                        write: false
                    verified_at: '2026-11-17T20:00:00Z'
                    created_at: '2026-11-17T20:00:00Z'
                    updated_at: '2026-11-17T20:00:00Z'
                    error: null
                    visibility: private
                    organization_id: motion-example
                    workspace_id: 4f20dcdd-f63b-4898-97d6-2e05c0d37c78
        '400':
          description: Invalid provider inputs or credential verification failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or revoked credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Required scope or current account access denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Private organization connection not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Provider setup is not configured or temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - MotionApiKey: []
        - MotionOAuth:
            - motion:connectors:read
components:
  schemas:
    MotionPrivateConnections:
      type: object
      properties:
        connections:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              connector_id:
                type: string
                enum:
                  - github
                  - notion
                  - google-drive
                  - getty
                  - s3
                  - tiktok
                  - youtube
                  - instagram
                  - facebook
                  - x
                  - threads
                  - linkedin
                  - reddit
                  - mastodon
                  - bluesky
                  - snapchat
                  - figma
                  - dropbox
                  - slack
                  - x-account
                description: Service ID; the connection id identifies a saved account.
              scope:
                type: string
                const: organization
                description: >-
                  Connection belongs to the credential’s organization and
                  workspace.
              visibility:
                type: string
                const: private
              organization_id:
                type: string
              workspace_id:
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              name:
                type: string
                description: Connected account display name.
              status:
                type: string
                enum:
                  - connected
                  - unverified
                  - needs_attention
                description: >-
                  Latest recorded verification: connected passed, unverified has
                  not been checked, needs_attention failed. Managed OAuth status
                  reconciles with the provider broker.
              can_use:
                type: boolean
                description: >-
                  Account passed verification and this actor may use it; project
                  template/kit and organization restrictions are checked during
                  execution.
              capabilities:
                type: object
                propertyNames:
                  type: string
                additionalProperties:
                  type: boolean
              permission_options:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    label:
                      type: string
                    write:
                      type: boolean
                  required:
                    - id
                    - label
                    - write
                  additionalProperties: false
              verified_at:
                description: >-
                  Time of the last provider verification, or null if not yet
                  checked.
                type:
                  - string
                  - 'null'
              created_at:
                type: string
              updated_at:
                type: string
              error:
                type:
                  - string
                  - 'null'
            required:
              - id
              - connector_id
              - scope
              - visibility
              - organization_id
              - workspace_id
              - name
              - status
              - can_use
              - capabilities
              - permission_options
              - verified_at
              - created_at
              - updated_at
              - error
            additionalProperties: false
          description: >-
            Your creator-private saved accounts in the credential organization
            workspace.
      required:
        - connections
      additionalProperties: false
    ErrorResponse:
      type: object
      description: >-
        Error bodies are JSON. Check the HTTP status first. Permission and
        validation errors use error; service errors may use detail. Optional
        fields explain how to correct the request.
      anyOf:
        - required:
            - error
        - required:
            - detail
      properties:
        error:
          type: string
          description: Error code or readable explanation.
        detail:
          type: string
          description: Readable explanation from the service.
        message:
          type: string
          description: Readable explanation accompanying an error code.
        error_description:
          type: string
          description: Authentication or permission explanation.
        required_scope:
          type: string
          description: Permission required by this operation.
        details:
          type: array
          description: Invalid request fields. Each issue includes a path and message.
          items:
            type: object
            properties:
              code:
                type: string
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
              message:
                type: string
        issues:
          type: array
          description: Service validation issues.
          items:
            type: object
  securitySchemes:
    MotionApiKey:
      type: http
      scheme: bearer
      description: >-
        A Motion API key. Access is limited to its stored organization,
        workspace, scopes and the creator’s current permissions.
    MotionOAuth:
      type: oauth2
      description: >-
        OAuth REST tokens use the full MCP audience, https://mcp.motion.so/mcp.
        Reauthorize existing connections to add scopes. Current workspace roles
        and resource permissions still apply.
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.motion.so/oauth/authorize
          tokenUrl: https://mcp.motion.so/oauth/token
          scopes:
            motion:automations:read: Read automation definitions, capabilities, runs, and analytics.
            motion:automations:write: Create, edit, delete, invoke, and retry automations.
            motion:connectors:read: >-
              Read available services, your private organization connections and
              allowed actions without secrets.
            motion:connectors:write: >-
              Connect and disconnect your private accounts inside the credential
              organization workspace.
            motion:templates:read: Read and preview accessible templates.
            motion:templates:write: Create, edit, share, and archive prompt templates.
            motion:sessions:read: Read permitted chats, job status and saved exports.
            motion:sessions:write: >-
              Create and steer Motion projects using organization workspace
              credits.
            motion:assets:read: Find and read permitted media library assets.
            motion:brand-kits:read: Read permitted brand kits.
            motion:brand-kits:write: Create and edit brand kits within current app permissions.
            motion:social:read: Read authorized social accounts and posts.
            motion:social:write: >-
              Draft, submit, approve and cancel posts within current app
              permissions.

````

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