Get your relation to a resource

GET/api/v2/workspaces/{slug}/permissions/relation/

Return the relation you hold on one resource. The relation is a role slug. On a workspace the system roles are owner, admin, member, and guest. On a project they are admin, contributor, commenter, and guest. A custom role uses its own slug. The response is {"relation": "<slug>"}, or {"relation": null} when you hold none.

Only a grant made to you, on exactly this resource, counts. An expired grant doesn't. A role you reach through a teamspace or inherit from a parent isn't reported, so null doesn't mean you have no access. To test access, call Check a permission.

An unknown resource_type returns null, not an error.

Any member of the workspace can call this endpoint, guests included.

Path Parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs. In https://app.plane.so/my-team/projects/, the slug is my-team.

Query Parameters

Both parameters are required. Leaving either out returns 400 with resource_type and resource_id are required.

resource_type:requiredstring

The kind of resource, as the permission engine names it, for example workspace, project, cycle, module, initiative, or teamspace.

resource_id:requiredstring (uuid)

The id of the resource. A value that isn't a UUID returns 400 with resource_id must be a UUID.

Scopes

workspaces.permissions:read

Errors

Status	Code	Cause
400	invalid_request	resource_type or resource_id is missing, or resource_id isn't a UUID.
401	unauthorized	Missing or invalid credentials.
402	payment_required	The feature this endpoint belongs to isn't enabled on your plan, or is switched off.
403	forbidden	You aren't a member of the workspace, or your token scope doesn't allow this.
404	not_found	No such workspace.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Get your relation to a resource

curl -X GET \
  "https://api.plane.so/api/v2/workspaces/my-team/permissions/relation/?resource_type=project&resource_id=4af68566-94a4-4eb3-94aa-50dc9427067b" \
  -H "X-Api-Key: $PLANE_API_KEY"

import requests

response = requests.get(
    "https://api.plane.so/api/v2/workspaces/my-team/permissions/relation/",
    headers={"X-Api-Key": "your-api-key"},
    params={
        "resource_type": "project",
        "resource_id": "4af68566-94a4-4eb3-94aa-50dc9427067b",
    },
)
print(response.json())

const params = new URLSearchParams({
  resource_type: "project",
  resource_id: "4af68566-94a4-4eb3-94aa-50dc9427067b",
});
const response = await fetch(
  `https://api.plane.so/api/v2/workspaces/my-team/permissions/relation/?${params}`,
  {
    headers: {
      "X-Api-Key": "your-api-key",
    },
  },
);
const data = await response.json();

Response200

{
  "relation": "contributor"
}

Response200

{
  "relation": null
}