This directory contains practical examples demonstrating how to use the Plane Python SDK.

Before running these examples, ensure you have:

1. Installed the Plane Python SDK:

pip install plane-sdk

2. Set up your environment variables:

export PLANE_BASE_URL="https://api.plane.so"
export PLANE_API_KEY="your-api-key"
export WORKSPACE_SLUG="your-workspace-slug"

See SETUP.md for detailed setup instructions.

Sets up a complete project with all necessary configurations:

• Creates a new project
• Creates work item types (Bug, Feature, Task, Story)
• Creates workflow states (Backlog, To Do, In Progress, In Review, Done, Cancelled)
• Creates labels for categorization

Run:

python examples/setup_project.py

Use this when:

• Starting a new project
• You need to configure work item types, states, and labels
• Setting up a standardized project structure

Creates a basic project and populates it with work items:

• Creates a simple project
• Sets up basic states (To Do, In Progress, Done)
• Creates a few labels
• Creates multiple work items with different priorities
• Lists all work items in the project

Run:

python examples/create_work_items.py

Use this when:

• You want a quick project setup
• You need to create and track work items
• Getting started with the SDK

Demonstrates OAuth 2.0 authentication flows:

• Authorization code flow (for web applications)
• Client credentials flow (for server-to-server)
• Bot token generation (for workspace app installations)
• Token refresh and revocation
• Error handling with OAuth

Run:

# Set OAuth environment variables
export OAUTH_CLIENT_ID="your_client_id"
export OAUTH_CLIENT_SECRET="your_client_secret"
export APP_INSTALLATION_ID="optional_installation_id"  # For bot token

python examples/oauth_example.py

Use this when:

• Building web applications that need user authorization
• Implementing server-to-server authentication
• Creating workspace app integrations with bot tokens
• Managing OAuth token lifecycle

1. Set up environment variables (see SETUP.md):

export PLANE_BASE_URL="https://api.plane.so"
export PLANE_API_KEY="your-api-key"
export WORKSPACE_SLUG="your-workspace-slug"

2. Run an example:

# Full project setup with types, states, and labels
python examples/setup_project.py

# Or create a simple project with work items
python examples/create_work_items.py

import os
from plane.client import PlaneClient

client = PlaneClient(
    base_url=os.environ["PLANE_BASE_URL"],
    api_key=os.environ["PLANE_API_KEY"]
)

from plane.models.projects import CreateProject

project = client.projects.create(
    workspace_slug="my-workspace",
    data=CreateProject(
        name="My Project",
        identifier="MP",
        description="Project description"
    )
)

from plane.models.states import CreateState

state = client.states.create(
    workspace_slug="my-workspace",
    project_id=project.id,
    data=CreateState(
        name="In Progress",
        group="started",
        color="#f59e0b"
    )
)

from plane.models.work_items import CreateWorkItem

work_item = client.work_items.create(
    workspace_slug="my-workspace",
    project_id=project.id,
    data=CreateWorkItem(
        name="Fix bug",
        description_html="<p>Description here</p>",
        state_id=state.id,
        priority="high"
    )
)

Always handle potential errors when using the SDK:

from plane.errors import HttpError, ConfigurationError

try:
    project = client.projects.create(workspace_slug, data=project_data)
except HttpError as e:
    print(f"HTTP error {e.status_code}: {e}")
except ConfigurationError as e:
    print(f"Configuration error: {e}")

• Setup issues? See SETUP.md
• SDK documentation: ../README.md
• API documentation: https://docs.plane.so
• Support: dev@plane.so

After running the examples:

1. Explore the SDK documentation for more features
2. Check the Plane API documentation for details
3. Build your own integrations using these examples as templates