Automate a workflow with Skills (Playbook)

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query GetTaskSkills($taskType: String!) { me { ... on WorkspaceUser { id workspace { id skills(taskType: $taskType, showCuratedSkills: true) { kind taskType name description status returnType updatedAt owner { id name email } } } } } }",
    "variables": { "taskType": "tax-prep" }
  }'

{
  "data": {
    "me": {
      "id": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
      "workspace": {
        "id": "018f9c20-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "skills": [
          {
            "kind": "WORKSPACE",
            "taskType": "tax-prep",
            "name": "check-w2-totals",
            "description": "Verify W-2 wage totals against binder extractions.",
            "status": "APPROVED",
            "returnType": "F1040",
            "updatedAt": "2026-06-22T10:14:00.000Z",
            "owner": {
              "id": "019f0fb6-3001-7900-b7bc-0d11288504b1",
              "name": "Jane Preparer",
              "email": "jane@example-firm.com"
            }
          },
          {
            "kind": "USER",
            "taskType": "tax-prep",
            "name": "my-firm-reconciliation",
            "description": "Personal reconciliation protocol.",
            "status": "NONE",
            "returnType": null,
            "updatedAt": "2026-07-04T18:22:01.000Z",
            "owner": {
              "id": "019f0fb6-3001-7900-b7bc-0d11288504b1",
              "name": "Jane Preparer",
              "email": "jane@example-firm.com"
            }
          }
        ]
      }
    }
  }
}

A skill is a reusable, versioned rule set the Filed analyst applies automatically during a tax prep or tax advisor run. Skills are scoped to a workspace (WORKSPACE skills, shared firm protocols) or to a single user (USER skills, personal protocols). The Playbook screen in the Filed web app is the human UI over this API. This recipe is the minimal call sequence to list a workspace’s skills for a task family, share a personal skill with the firm, approve or deny that promotion, toggle a skill on or off, and scope which skills apply to a single run. Every call uses a workspaceToken (see Authentication) and goes to the single GraphQL endpoint:

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

This recipe does not re-document the types it touches. For the full Skill, SkillRule, SkillStrategy, SkillActivityEvent, and UserShortDetails field lists, the SkillKind and SkillStatus enums, and the deleteSkill mutation, see Skills.

1. List a workspace’s skills for a task type

There is no top-level skills query. Read workspace.skills through me { ... on WorkspaceUser { workspace { skills(...) } } } (see Skills). Pass taskType to scope the list to one task family, and showCuratedSkills: true to include Filed’s curated built-in skills alongside the workspace’s own.

query GetTaskSkills($taskType: String!) {
  me {
    ... on WorkspaceUser {
      id
      workspace {
        id
        skills(taskType: $taskType, showCuratedSkills: true) {
          kind
          taskType
          name
          description
          status
          returnType
          updatedAt
          owner {
            id
            name
            email
          }
        }
      }
    }
  }
}

{
  "taskType": "tax-prep"
}

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query GetTaskSkills($taskType: String!) { me { ... on WorkspaceUser { id workspace { id skills(taskType: $taskType, showCuratedSkills: true) { kind taskType name description status returnType updatedAt owner { id name email } } } } } }",
    "variables": { "taskType": "tax-prep" }
  }'

{
  "data": {
    "me": {
      "id": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
      "workspace": {
        "id": "018f9c20-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "skills": [
          {
            "kind": "WORKSPACE",
            "taskType": "tax-prep",
            "name": "check-w2-totals",
            "description": "Verify W-2 wage totals against binder extractions.",
            "status": "APPROVED",
            "returnType": "F1040",
            "updatedAt": "2026-06-22T10:14:00.000Z",
            "owner": {
              "id": "019f0fb6-3001-7900-b7bc-0d11288504b1",
              "name": "Jane Preparer",
              "email": "jane@example-firm.com"
            }
          },
          {
            "kind": "USER",
            "taskType": "tax-prep",
            "name": "my-firm-reconciliation",
            "description": "Personal reconciliation protocol.",
            "status": "NONE",
            "returnType": null,
            "updatedAt": "2026-07-04T18:22:01.000Z",
            "owner": {
              "id": "019f0fb6-3001-7900-b7bc-0d11288504b1",
              "name": "Jane Preparer",
              "email": "jane@example-firm.com"
            }
          }
        ]
      }
    }
  }
}

Pick the USER skill you want to share with the firm. Save its taskType and name; the promotion mutations in steps 3 and 4 identify a skill by those two values (no kind argument).

2. Fetch one skill’s detail and activity

Before promoting a skill, read its full detail and activity timeline with workspace.skill. Identify the skill with kind + taskType + name (and optional returnType when the skill is scoped to a return type).

query GetSkill(
  $kind: SkillKind!
  $taskType: String!
  $name: String!
  $returnType: ReturnType
) {
  me {
    ... on WorkspaceUser {
      id
      workspace {
        id
        skill(
          kind: $kind
          taskType: $taskType
          name: $name
          returnType: $returnType
        ) {
          kind
          taskType
          name
          description
          body
          status
          returnType
          updatedAt
          owner {
            id
            name
            email
          }
          activity {
            action
            timestamp
            note
            triggeredBy {
              id
              name
              email
            }
          }
        }
      }
    }
  }
}

{
  "kind": "USER",
  "taskType": "tax-prep",
  "name": "my-firm-reconciliation"
}

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "query GetSkill($kind: SkillKind!, $taskType: String!, $name: String!, $returnType: ReturnType) { me { ... on WorkspaceUser { id workspace { id skill(kind: $kind, taskType: $taskType, name: $name, returnType: $returnType) { kind taskType name description body status returnType updatedAt owner { id name email } activity { action timestamp note triggeredBy { id name email } } } } } } }",
    "variables": {
      "kind": "USER",
      "taskType": "tax-prep",
      "name": "my-firm-reconciliation"
    }
  }'

{
  "data": {
    "me": {
      "id": "019f0fb6-37b1-7800-b7bc-0d11288504b1",
      "workspace": {
        "id": "018f9c20-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "skill": {
          "kind": "USER",
          "taskType": "tax-prep",
          "name": "my-firm-reconciliation",
          "description": "Personal reconciliation protocol.",
          "body": "Flag any 1099-B where proceeds differ from the broker statement by more than $1, and surface the discrepancy as a review item.",
          "status": "NONE",
          "returnType": null,
          "updatedAt": "2026-07-04T18:22:01.000Z",
          "owner": {
            "id": "019f0fb6-3001-7900-b7bc-0d11288504b1",
            "name": "Jane Preparer",
            "email": "jane@example-firm.com"
          },
          "activity": [
            {
              "action": "created",
              "timestamp": "2026-07-04T18:22:01.000Z",
              "note": null,
              "triggeredBy": {
                "id": "019f0fb6-3001-7900-b7bc-0d11288504b1",
                "name": "Jane Preparer",
                "email": "jane@example-firm.com"
              }
            }
          ]
        }
      }
    }
  }
}

workspace.skill returns null when no skill matches the supplied kind + taskType + name (+ returnType). Handle null as a not-found result before you try to promote. See Skills, view a single skill.

3. Request promoting a personal skill to the workspace

requestSkillPromotion submits a USER skill for firm-wide review. The skill’s status moves from NONE to PENDING. A workspace admin then approves or denies it in step 4. The mutation identifies the skill by taskType + name only; there is no kind argument because only USER skills can be promoted.

mutation RequestSkillPromotion($taskType: String!, $name: String!) {
  requestSkillPromotion(taskType: $taskType, name: $name) {
    kind
    taskType
    name
    status
  }
}

{
  "taskType": "tax-prep",
  "name": "my-firm-reconciliation"
}

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "mutation RequestSkillPromotion($taskType: String!, $name: String!) { requestSkillPromotion(taskType: $taskType, name: $name) { kind taskType name status } }",
    "variables": { "taskType": "tax-prep", "name": "my-firm-reconciliation" }
  }'

{
  "data": {
    "requestSkillPromotion": {
      "kind": "USER",
      "taskType": "tax-prep",
      "name": "my-firm-reconciliation",
      "status": "PENDING"
    }
  }
}

4. Approve or deny the promotion

A workspace admin resolves the PENDING promotion with one of two mutations. Both identify the skill by taskType + name and return the updated Skill. To approve, call approveSkillPromotion. The skill’s status becomes APPROVED and it applies firm-wide.

mutation ApproveSkillPromotion($taskType: String!, $name: String!) {
  approveSkillPromotion(taskType: $taskType, name: $name) {
    kind
    taskType
    name
    status
  }
}

{
  "taskType": "tax-prep",
  "name": "my-firm-reconciliation"
}

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "mutation ApproveSkillPromotion($taskType: String!, $name: String!) { approveSkillPromotion(taskType: $taskType, name: $name) { kind taskType name status } }",
    "variables": { "taskType": "tax-prep", "name": "my-firm-reconciliation" }
  }'

{
  "data": {
    "approveSkillPromotion": {
      "kind": "USER",
      "taskType": "tax-prep",
      "name": "my-firm-reconciliation",
      "status": "APPROVED"
    }
  }
}

To deny, call denySkillPromotion. The skill’s status becomes DENIED and the optional reason is recorded on the activity timeline so the owner can see why the promotion was rejected.

mutation DenySkillPromotion(
  $taskType: String!
  $name: String!
  $reason: String
) {
  denySkillPromotion(taskType: $taskType, name: $name, reason: $reason) {
    kind
    taskType
    name
    status
  }
}

{
  "taskType": "tax-prep",
  "name": "my-firm-reconciliation",
  "reason": "Overlaps with existing firm protocol check-w2-totals."
}

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "mutation DenySkillPromotion($taskType: String!, $name: String!, $reason: String) { denySkillPromotion(taskType: $taskType, name: $name, reason: $reason) { kind taskType name status } }",
    "variables": {
      "taskType": "tax-prep",
      "name": "my-firm-reconciliation",
      "reason": "Overlaps with existing firm protocol check-w2-totals."
    }
  }'

{
  "data": {
    "denySkillPromotion": {
      "kind": "USER",
      "taskType": "tax-prep",
      "name": "my-firm-reconciliation",
      "status": "DENIED"
    }
  }
}

After any of the promotion mutations, refetch GetTaskSkills and GetSkill so the Playbook UI reflects the new status. The web app calls client.refetchQueries({ include: ["GetTaskSkills", "GetSkill"] }) after every bulk action. See Skills, toggle a skill active or inactive.

5. Toggle a skill active or inactive

setSkillActive enables or disables a skill without deleting it. Disabling sets status: DISABLED so the skill stops applying during runs but is still listed and can be re-enabled. Pass returnType when the skill is scoped to a return type.

mutation SetSkillActive(
  $taskType: String!
  $name: String!
  $active: Boolean!
  $returnType: ReturnType
) {
  setSkillActive(
    taskType: $taskType
    name: $name
    active: $active
    returnType: $returnType
  ) {
    kind
    taskType
    name
    status
  }
}

{
  "taskType": "tax-prep",
  "name": "check-w2-totals",
  "active": false,
  "returnType": "F1040"
}

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "mutation SetSkillActive($taskType: String!, $name: String!, $active: Boolean!, $returnType: ReturnType) { setSkillActive(taskType: $taskType, name: $name, active: $active, returnType: $returnType) { kind taskType name status } }",
    "variables": {
      "taskType": "tax-prep",
      "name": "check-w2-totals",
      "active": false,
      "returnType": "F1040"
    }
  }'

{
  "data": {
    "setSkillActive": {
      "kind": "WORKSPACE",
      "taskType": "tax-prep",
      "name": "check-w2-totals",
      "status": "DISABLED"
    }
  }
}

Re-enable the same skill by calling setSkillActive again with active: true; its status returns to APPROVED.

There is no runSkill mutation. Skills are never invoked directly. The analyst applies every APPROVED (active) skill automatically during a triggerTaxPrep or triggerTaxAdvisor run. The next section shows how to scope which active skills apply to one specific run.

6. Scope which skills apply to a single run

Because skills apply automatically based on their status, the way to control which skills a particular run uses is the optional skills argument (RunSkillSelectionInput) on the trigger mutations:

triggerTaxPrep(input: { ..., skills: { workspace: [...], user: [...] } }) for a tax prep run.
triggerTaxAdvisor(input: { ..., skills: { workspace: [...], user: [...] } }) or initiateTaxAdvisor(input: { ..., skills: { workspace: [...], user: [...] } }) for a tax advisor run.

RunSkillSelectionInput takes two optional lists of skill names:

input RunSkillSelectionInput {
  workspace: [String!]
  user: [String!]
}

Omit skills entirely to apply all active skills in both scopes. Pass an empty list in one scope to censor every skill in that scope. Pass a non-empty list to apply only those named skills. For example, to start a tax prep run that applies only the workspace skill check-w2-totals and the user skill my-firm-reconciliation, and no others:

mutation TriggerTaxPrep($input: TriggerTaxPrepInput!) {
  triggerTaxPrep(input: $input) {
    taskId
  }
}

{
  "input": {
    "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
    "returnType": "F1040",
    "skills": {
      "workspace": ["check-w2-totals"],
      "user": ["my-firm-reconciliation"]
    }
  }
}

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{
    "query": "mutation TriggerTaxPrep($input: TriggerTaxPrepInput!) { triggerTaxPrep(input: $input) { taskId } }",
    "variables": {
      "input": {
        "clientId": "018f9c2a-3d5f-7a10-b2c4-9e8d7f6a5b4c",
        "returnType": "F1040",
        "skills": {
          "workspace": ["check-w2-totals"],
          "user": ["my-firm-reconciliation"]
        }
      }
    }
  }'

{
  "data": {
    "triggerTaxPrep": {
      "taskId": "018f9c2c-4a1b-7e20-8b33-7c4d5e6f7080"
    }
  }
}

Poll the returned taskId per Run tax prep end to end and Tasks. The selected skills shape the review items the analyst raises during the run.

Next steps

For the full Skill, SkillRule, SkillStrategy, SkillActivityEvent, and UserShortDetails field lists, the SkillKind and SkillStatus enums, and the deleteSkill mutation, see Skills.
To run tax prep with the active skills and read the resulting review items, see Run tax prep end to end and Tax prep.
To run tax planning with the active skills and read the resulting strategies, see Run tax planning / advisory and Tax planning.

Run tax planning / advisory

Guides

Recipes

Automate a workflow with Skills (Playbook)

1. List a workspace’s skills for a task type

2. Fetch one skill’s detail and activity

3. Request promoting a personal skill to the workspace

4. Approve or deny the promotion

5. Toggle a skill active or inactive

6. Scope which skills apply to a single run

Next steps

​1. List a workspace’s skills for a task type

​2. Fetch one skill’s detail and activity

​3. Request promoting a personal skill to the workspace

​4. Approve or deny the promotion

​5. Toggle a skill active or inactive

​6. Scope which skills apply to a single run

​Next steps

1. List a workspace’s skills for a task type

2. Fetch one skill’s detail and activity

3. Request promoting a personal skill to the workspace

4. Approve or deny the promotion

5. Toggle a skill active or inactive

6. Scope which skills apply to a single run

Next steps