Skip to content
Docs
Project management

Plane

Let hires find, create, update and comment on work items and plan cycles in Plane, on Plane Cloud or your own server.

Explore 9 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Plane (open source), a hire can list your projects, search and list work items, read one with its comments, create work items, change their name, description, state or priority, comment, see cycles and add work items to a cycle. It works the same on Plane Cloud and on a Plane you run yourself.

1. Make an API key in Plane

  1. Open Personal access tokens in Plane Cloud (the form in Roster links there too). If you run Plane yourself, it's the same page on your Plane: Profile settings → Personal access tokens.
  2. Click Add personal access token, name it Roster and copy the token.

What hires do shows as the token's owner, so you may want a Plane member just for Roster.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Plane and choose it.
  2. API key: paste the token.
  3. Plane address: leave https://api.plane.so for Plane Cloud. If you run Plane yourself, put your Plane's address, like https://plane.example.com.
  4. Workspace: your workspace's slug, from your Plane address. In app.plane.so/acme/projects/ it's acme.
  5. Click Connect. Roster checks the key on your workspace's projects, and the connection shows Connected as acme (your workspace). If Plane refuses the key, or the workspace doesn't exist, Roster says so and saves nothing.
Connecting Plane
Connecting Plane

3. Give hires access

On the hire's Tools tab, click Give access on Plane:

  • Read only: it can list, search and read work items and cycles, and nothing else.
  • Read and write: it can also create and update work items, comment and add them to cycles.
  • Projects: project identifiers like WEB. Leave it empty for every project the key can reach. Anything outside the list is refused.
What a hire may do in Plane
What a hire may do in Plane

Hires refer to work items by their key, like WEB-12, and to states and cycles by name, so they can say "moved WEB-12 to In Progress" the way your team does.

Watching for changes

With projects listed, a hire's responsibility can watch Plane: when work items in those projects change, the hire is woken with the list. Checking costs nothing when nothing changed.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Plane and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In Plane: Profile settings → Personal access tokens → Add token. Hires' work shows as the token's owner.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Plane connection fields
FieldWhat to provide
API key
apiKey
Required · sealed secret		In Plane: Profile settings → Personal access tokens → Add token. Hires' work shows as the token's owner.
Plane address
url
Optional		Leave as it is for Plane Cloud. Self-hosted: your Plane's address, like https://plane.example.com.

Starts with: https://api.plane.so.

Workspace
workspace
Required		From your Plane address: in app.plane.so/acme/projects it's acme.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Plane per-hire limits
FieldWhat to provide
Projects
projects
Optional		Project identifiers like WEB. Leave empty for every project the key can reach.

Actions

9 actions: 5 only read and 4 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

9 of 9 actions. Open an action for its arguments and full input schema.

list_projectsRead only

The Plane projects this hire can use, with their identifiers.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
search_work_itemsRead only

Search work items by words in their name or by key. Up to 20 matches.

Approval: Uses your workspace and hire approval settings.

Arguments for search_work_items
ArgumentTypeDetails
queryRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "query"
  ]
}
list_work_itemsRead only

A project's work items, most recently updated first, optionally only those in one state.

Approval: Uses your workspace and hire approval settings.

Arguments for list_work_items
ArgumentTypeDetails
projectRequiredstringproject identifier, e.g. WEB
stateOptionalstringonly items in this state, e.g. In Progress
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "minLength": 1,
      "description": "project identifier, e.g. WEB"
    },
    "state": {
      "description": "only items in this state, e.g. In Progress",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "project"
  ]
}
get_work_itemRead only

A work item's description, state, priority, assignees and latest comments.

Approval: Uses your workspace and hire approval settings.

Arguments for get_work_item
ArgumentTypeDetails
idRequiredstringwork item, e.g. WEB-12
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^([A-Za-z0-9]{1,12})-(\\d+)$",
      "description": "work item, e.g. WEB-12"
    }
  },
  "required": [
    "id"
  ]
}
create_work_itemRead and write

Create a work item in a project.

Approval: Uses your workspace and hire approval settings.

Arguments for create_work_item
ArgumentTypeDetails
projectRequiredstringproject identifier, e.g. WEB
nameRequiredstringSee input schema below.
descriptionOptionalstringplain text; blank lines start new paragraphsDefault: ""
priorityOptional"urgent" | "high" | "medium" | "low" | "none"See input schema below.
stateOptionalstringa state name, e.g. Todo; default: the project's default
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "minLength": 1,
      "description": "project identifier, e.g. WEB"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description": {
      "default": "",
      "description": "plain text; blank lines start new paragraphs",
      "type": "string"
    },
    "priority": {
      "type": "string",
      "enum": [
        "urgent",
        "high",
        "medium",
        "low",
        "none"
      ]
    },
    "state": {
      "description": "a state name, e.g. Todo; default: the project's default",
      "type": "string"
    }
  },
  "required": [
    "project",
    "name"
  ]
}
update_work_itemRead and write

Change a work item's name, description, state or priority. Only what's given changes.

Approval: Uses your workspace and hire approval settings.

Arguments for update_work_item
ArgumentTypeDetails
idRequiredstringwork item, e.g. WEB-12
nameOptionalstringSee input schema below.
descriptionOptionalstringreplaces the description; plain text
stateOptionalstringa state name, e.g. In Progress or Done
priorityOptional"urgent" | "high" | "medium" | "low" | "none"See input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^([A-Za-z0-9]{1,12})-(\\d+)$",
      "description": "work item, e.g. WEB-12"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "description": {
      "description": "replaces the description; plain text",
      "type": "string"
    },
    "state": {
      "description": "a state name, e.g. In Progress or Done",
      "type": "string"
    },
    "priority": {
      "type": "string",
      "enum": [
        "urgent",
        "high",
        "medium",
        "low",
        "none"
      ]
    }
  },
  "required": [
    "id"
  ]
}
commentRead and write

Comment on a work item.

Approval: Uses your workspace and hire approval settings.

Arguments for comment
ArgumentTypeDetails
idRequiredstringwork item, e.g. WEB-12
bodyRequiredstringplain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^([A-Za-z0-9]{1,12})-(\\d+)$",
      "description": "work item, e.g. WEB-12"
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "description": "plain text"
    }
  },
  "required": [
    "id",
    "body"
  ]
}
list_cyclesRead only

A project's cycles (sprints) with their dates and progress.

Approval: Uses your workspace and hire approval settings.

Arguments for list_cycles
ArgumentTypeDetails
projectRequiredstringproject identifier, e.g. WEB
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "minLength": 1,
      "description": "project identifier, e.g. WEB"
    }
  },
  "required": [
    "project"
  ]
}
add_to_cycleRead and write

Add a work item to one of its project's cycles, by the cycle's name.

Approval: Uses your workspace and hire approval settings.

Arguments for add_to_cycle
ArgumentTypeDetails
idRequiredstringwork item, e.g. WEB-12
cycleRequiredstringthe cycle's name
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^([A-Za-z0-9]{1,12})-(\\d+)$",
      "description": "work item, e.g. WEB-12"
    },
    "cycle": {
      "type": "string",
      "minLength": 1,
      "description": "the cycle's name"
    }
  },
  "required": [
    "id",
    "cycle"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

OpenProject

Open-source project management: work packages, boards and Gantt.

Smartsheet

Sheets, rows and reports in Smartsheet.

On this page

1. Make an API key in Plane2. Connect it in Roster3. Give hires accessTools and permissions reference