Integration Capabilities - Filed Engineering

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 query as a WorkspaceUser, so authenticate with a workspaceToken. All requests go to:

https://router.apps.filed.com/graphql

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

Capability model

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

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!
}

Workspace.connections

[Connection!]!

The workspace’s configured integration connections. Pass providerKey to return only connections for one provider.

Workspace.providers

[IntegrationProvider!]!

The provider catalog available to the workspace. Each provider includes its capability definitions.

Workspace.connectionCapabilityRun

ConnectionCapabilityRun

Fetches the current status and result for a previously started capability run. Returns null if the run cannot be found in the workspace.

Connection.id

ID!

The connection ID you pass to runConnectionCapabliltity.

Connection.providerKey

String!

The provider key for the connection. Match this against IntegrationProvider.id to understand which capabilities can run on the connection.

Connection.status

ConnectionStatus!

The current lifecycle status of the connection. Only run capabilities on a connection that is ready for the provider action you need.

IntegrationProvider.id

String!

The provider key, for example a document management provider or tax software provider key.

IntegrationProvider.category

String!

The provider category used for grouping in the product.

IntegrationProvider.profile

ProviderProfile!

Display information, help link, description, and the provider’s capabilities.

IntegrationProvider.capability

ProviderCapability

Looks up one capability by value. Returns null if the provider does not advertise that capability.

ProviderCapability.value

String!

The machine-readable capability identifier. Send this exact string as the capability input when running the capability.

ProviderCapability.label

String!

Human-readable capability name.

ProviderCapability.description

String

Optional human-readable detail about what the capability does.

ProviderCapability.kind

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.

ProviderCapability.inputSchema

JSON

The JSON schema for the params object expected by runConnectionCapabliltity. Use this to construct valid parameters.

ProviderCapability.outputSchema

JSON

The JSON schema for the result returned after the capability run completes.

List provider capabilities

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

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

{
  "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.

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

{
  "value": "files.list"
}

Arguments

value

String!

required

The exact ProviderCapability.value to look up on each provider.

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.

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

{
  "providerKey": "example-dms"
}

Arguments

providerKey

String

Optional provider key. Omit it to return connections for all providers.

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.

mutation RunConnectionCapabliltity($input: RunConnectionCapabliltityInput!) {
  runConnectionCapabliltity(input: $input) {
    id
    status
    error
    result
  }
}

input RunConnectionCapabliltityInput {
  connectionId: ID!
  capability: String!
  params: JSON!
}

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

Arguments

input.connectionId

ID!

required

The connection to run the capability against. Get this from workspace.connections.

input.capability

String!

required

The exact ProviderCapability.value to run.

input.params

JSON!

required

The capability parameters. Shape this object from the capability’s inputSchema. Send {} when the schema accepts an empty object.

Response

ID!

The capability run ID. Poll workspace.connectionCapabilityRun(id:) with this value.

status

String!

The Temporal workflow status. A newly started run usually returns RUNNING.

error

String

Error detail when the run fails. null while the run is running or when it completes successfully.

result

JSON

The provider-specific result. null until the workflow returns a result.

Example request

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

Example response

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

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

Poll a capability run

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

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

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

Arguments

ID!

required

The ID returned by runConnectionCapabliltity.

Response

connectionCapabilityRun

ConnectionCapabilityRun

The run status and result. Returns null if the run does not exist or does not belong to the authenticated workspace.

{
  "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:

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

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.

​Capability model

​List provider capabilities

​Look up one capability

​Arguments

​List connections for a provider

​Arguments

​Run a capability

​Arguments

​Response

​Example request

​Example response

​Poll a capability run

​Arguments

​Response

​MCP usage pattern

Capability model

List provider capabilities

Look up one capability

Arguments

List connections for a provider

Arguments

Run a capability

Arguments

Response

Example request

Example response

Poll a capability run

Arguments

Response

MCP usage pattern