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

# Integration Capabilities

> List provider capabilities, run a capability on a connection, and poll the capability run result

Integration capabilities are the provider-specific actions Filed can run against
a connected integration. Use them when an integration needs to expose a concrete
operation such as listing files, downloading a document, syncing data, or
running a tax software action.

Capabilities are reached through the [`me`](/apis/me) query as a
`WorkspaceUser`, so authenticate with a **`workspaceToken`**. All requests go to:

```http theme={null}
https://router.apps.filed.com/graphql
```

<Note>
  The run mutation is currently named `runConnectionCapabliltity` in the GraphQL
  schema. The spelling includes `Capabliltity`. Use that exact field name until
  the schema changes.
</Note>

## Capability model

Capabilities are advertised on each provider. A provider belongs to a workspace,
and a connection points at one provider by `providerKey`.

```graphql theme={null}
type Workspace {
  connections(providerKey: String): [Connection!]!
  providers: [IntegrationProvider!]!
  connectionCapabilityRun(id: ID!): ConnectionCapabilityRun
}

type Connection {
  id: ID!
  providerKey: String!
  name: String!
  provider: IntegrationProvider!
  status: ConnectionStatus!
  use: ConnectionUse!
  settings: JSON
  actions: JSON
  errorReason: String
  userId: ID!
  workspaceId: ID!
  user: UserShortDetails!
  artifact(path: String): SignedPath
  clients(search: String, offset: Int, limit: Int): [ConnectionClient!]!
  jobs(filters: ConnectionJobFilters, limit: Int): [ConnectionJob!]!
  transferRootFolder: String
  authenticatorConfigured: Boolean!
  botEmailAddress: String
  createdAt: Date!
}

type IntegrationProvider {
  id: String!
  category: String!
  profile: ProviderProfile!
  capability(value: String!): ProviderCapability
}

type ProviderProfile {
  display: ProviderDisplay!
  description: String!
  helpCenterUrl: String
  capabilities: [ProviderCapability!]!
}

type ProviderCapability {
  value: String!
  label: String!
  description: String
  kind: String
  inputSchema: JSON
  outputSchema: JSON
}

type ProviderDisplay {
  bgColor: String!
  textColor: String!
  logoUrl: String
  shortName: String!
  fullName: String!
}
```

<ResponseField name="Workspace.connections" type="[Connection!]!">
  The workspace's configured integration connections. Pass `providerKey` to return
  only connections for one provider.
</ResponseField>

<ResponseField name="Workspace.providers" type="[IntegrationProvider!]!">
  The provider catalog available to the workspace. Each provider includes its
  capability definitions.
</ResponseField>

<ResponseField name="Workspace.connectionCapabilityRun" type="ConnectionCapabilityRun">
  Fetches the current status and result for a previously started capability run.
  Returns `null` if the run cannot be found in the workspace.
</ResponseField>

<ResponseField name="Connection.id" type="ID!">
  The connection ID you pass to `runConnectionCapabliltity`.
</ResponseField>

<ResponseField name="Connection.providerKey" type="String!">
  The provider key for the connection. Match this against `IntegrationProvider.id`
  to understand which capabilities can run on the connection.
</ResponseField>

<ResponseField name="Connection.status" type="ConnectionStatus!">
  The current lifecycle status of the connection. Only run capabilities on a
  connection that is ready for the provider action you need.
</ResponseField>

<ResponseField name="IntegrationProvider.id" type="String!">
  The provider key, for example a document management provider or tax software
  provider key.
</ResponseField>

<ResponseField name="IntegrationProvider.category" type="String!">
  The provider category used for grouping in the product.
</ResponseField>

<ResponseField name="IntegrationProvider.profile" type="ProviderProfile!">
  Display information, help link, description, and the provider's capabilities.
</ResponseField>

<ResponseField name="IntegrationProvider.capability" type="ProviderCapability">
  Looks up one capability by `value`. Returns `null` if the provider does not
  advertise that capability.
</ResponseField>

<ResponseField name="ProviderCapability.value" type="String!">
  The machine-readable capability identifier. Send this exact string as the
  `capability` input when running the capability.
</ResponseField>

<ResponseField name="ProviderCapability.label" type="String!">
  Human-readable capability name.
</ResponseField>

<ResponseField name="ProviderCapability.description" type="String">
  Optional human-readable detail about what the capability does.
</ResponseField>

<ResponseField name="ProviderCapability.kind" type="String">
  The capability type reported by the provider workflow, commonly `query` or
  `mutation`. `query` capabilities read data. `mutation` capabilities can create,
  update, move, delete, sync, or otherwise change state.
</ResponseField>

<ResponseField name="ProviderCapability.inputSchema" type="JSON">
  The JSON schema for the `params` object expected by
  `runConnectionCapabliltity`. Use this to construct valid parameters.
</ResponseField>

<ResponseField name="ProviderCapability.outputSchema" type="JSON">
  The JSON schema for the `result` returned after the capability run completes.
</ResponseField>

## List provider capabilities

Read `workspace.providers` to discover available providers and their capability
definitions.

```graphql theme={null}
query ListIntegrationCapabilities {
  me {
    ... on WorkspaceUser {
      workspace {
        providers {
          id
          category
          profile {
            display {
              fullName
              shortName
            }
            capabilities {
              value
              label
              description
              kind
              inputSchema
              outputSchema
            }
          }
        }
      }
    }
  }
}
```

```json theme={null}
{
  "data": {
    "me": {
      "workspace": {
        "providers": [
          {
            "id": "example-dms",
            "category": "dms",
            "profile": {
              "display": {
                "fullName": "Example DMS",
                "shortName": "DMS"
              },
              "capabilities": [
                {
                  "value": "files.list",
                  "label": "List files",
                  "description": "List files from the connected document system",
                  "kind": "query",
                  "inputSchema": {
                    "type": "object",
                    "properties": {
                      "path": { "type": "string" }
                    }
                  },
                  "outputSchema": {
                    "type": "object",
                    "properties": {
                      "files": { "type": "array" }
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
}
```

## Look up one capability

Use `IntegrationProvider.capability(value:)` when you already know the provider
and capability value and only need that one definition.

```graphql theme={null}
query GetIntegrationCapability($value: String!) {
  me {
    ... on WorkspaceUser {
      workspace {
        providers {
          id
          capability(value: $value) {
            value
            label
            description
            kind
            inputSchema
            outputSchema
          }
        }
      }
    }
  }
}
```

```json theme={null}
{
  "value": "files.list"
}
```

### Arguments

<ParamField path="value" type="String!" required>
  The exact `ProviderCapability.value` to look up on each provider.
</ParamField>

## List connections for a provider

Capabilities run on a specific connection, not directly on a provider. Use
`workspace.connections(providerKey:)` to find the connection ID.

```graphql theme={null}
query ListProviderConnections($providerKey: String) {
  me {
    ... on WorkspaceUser {
      workspace {
        connections(providerKey: $providerKey) {
          id
          providerKey
          name
          status
          errorReason
        }
      }
    }
  }
}
```

```json theme={null}
{
  "providerKey": "example-dms"
}
```

### Arguments

<ParamField path="providerKey" type="String">
  Optional provider key. Omit it to return connections for all providers.
</ParamField>

## Run a capability

Use `runConnectionCapabliltity` to start a provider capability workflow. The
mutation validates `params` against the provider capability's `inputSchema`,
refreshes the connection credentials when possible, starts a background run, and
returns a run ID.

```graphql theme={null}
mutation RunConnectionCapabliltity($input: RunConnectionCapabliltityInput!) {
  runConnectionCapabliltity(input: $input) {
    id
    status
    error
    result
  }
}
```

```graphql theme={null}
input RunConnectionCapabliltityInput {
  connectionId: ID!
  capability: String!
  params: JSON!
}

type ConnectionCapabilityRun {
  id: ID!
  status: String!
  error: String
  result: JSON
}
```

### Arguments

<ParamField path="input.connectionId" type="ID!" required>
  The connection to run the capability against. Get this from
  `workspace.connections`.
</ParamField>

<ParamField path="input.capability" type="String!" required>
  The exact `ProviderCapability.value` to run.
</ParamField>

<ParamField path="input.params" type="JSON!" required>
  The capability parameters. Shape this object from the capability's
  `inputSchema`. Send `{}` when the schema accepts an empty object.
</ParamField>

### Response

<ResponseField name="id" type="ID!">
  The capability run ID. Poll `workspace.connectionCapabilityRun(id:)` with this
  value.
</ResponseField>

<ResponseField name="status" type="String!">
  The Temporal workflow status. A newly started run usually returns `RUNNING`.
</ResponseField>

<ResponseField name="error" type="String">
  Error detail when the run fails. `null` while the run is running or when it
  completes successfully.
</ResponseField>

<ResponseField name="result" type="JSON">
  The provider-specific result. `null` until the workflow returns a result.
</ResponseField>

### Example request

```json theme={null}
{
  "input": {
    "connectionId": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
    "capability": "files.list",
    "params": {
      "path": "/"
    }
  }
}
```

### Example response

```json theme={null}
{
  "data": {
    "runConnectionCapabliltity": {
      "id": "capability/example-dms/files.list/019f0fba-2b44-73dd-9f22-1dd2e2bb8a4b",
      "status": "RUNNING",
      "error": null,
      "result": null
    }
  }
}
```

<Warning>
  Check `ProviderCapability.kind` before running a capability. A `mutation`
  capability can change provider state, such as moving, deleting, uploading, or
  syncing records.
</Warning>

## Poll a capability run

After the mutation returns a run ID, poll
`workspace.connectionCapabilityRun(id:)` until the run completes or fails.

```graphql theme={null}
query CapabilityRun($id: ID!) {
  me {
    ... on WorkspaceUser {
      workspace {
        connectionCapabilityRun(id: $id) {
          id
          status
          error
          result
        }
      }
    }
  }
}
```

```json theme={null}
{
  "id": "capability/example-dms/files.list/019f0fba-2b44-73dd-9f22-1dd2e2bb8a4b"
}
```

### Arguments

<ParamField path="id" type="ID!" required>
  The ID returned by `runConnectionCapabliltity`.
</ParamField>

### Response

<ResponseField name="connectionCapabilityRun" type="ConnectionCapabilityRun">
  The run status and result. Returns `null` if the run does not exist or does not
  belong to the authenticated workspace.
</ResponseField>

```json theme={null}
{
  "data": {
    "me": {
      "workspace": {
        "connectionCapabilityRun": {
          "id": "capability/example-dms/files.list/019f0fba-2b44-73dd-9f22-1dd2e2bb8a4b",
          "status": "COMPLETED",
          "error": null,
          "result": {
            "files": [
              {
                "id": "file_123",
                "name": "2025 organizer.pdf"
              }
            ]
          }
        }
      }
    }
  }
}
```

## MCP usage pattern

For Filed MCP tools and AI agents, use this sequence:

1. Query `workspace.providers` and read `ProviderCapability.inputSchema`.
2. Query `workspace.connections(providerKey:)` and choose the connection ID.
3. If the capability `kind` is `mutation`, confirm the action with the user.
4. Call `runConnectionCapabliltity` with schema-valid `params`.
5. Poll `workspace.connectionCapabilityRun(id:)` until the run is no longer
   `RUNNING`.

<Tip>
  Do not invent capability parameter names. The provider's `inputSchema` is the
  source of truth for `params`, and each provider can expose a different shape.
</Tip>