team-plain/plain-support

Plain API Skill

Access to the Plain customer support platform via GraphQL API. This skill provides commands to read customers, support threads, timeline entries, help center content, and more. Notes can be added to threads. Help center articles can be created, updated, and published directly.

Prerequisites

• PLAIN_API_KEY environment variable set with your API key
• curl and jq installed

Quick Reference

Customers (Read Only)

# List customers
scripts/plain-api.sh customer list --first 10

# Get customer by ID
scripts/plain-api.sh customer get c_01ABC...

# Get customer by email
scripts/plain-api.sh customer get-by-email [email protected]

# Get customer by external ID
scripts/plain-api.sh customer get-by-external-id your-system-id

# Search customers
scripts/plain-api.sh customer search "john doe"

Threads (Read + Write)

# List threads (TODO status by default)
scripts/plain-api.sh thread list --first 20

# List all threads including done
scripts/plain-api.sh thread list --status all

# List done threads
scripts/plain-api.sh thread list --status DONE

# List threads by priority
scripts/plain-api.sh thread list --priority urgent
scripts/plain-api.sh thread list --priority high
scripts/plain-api.sh thread list --status TODO --priority low

# Get thread details
scripts/plain-api.sh thread get th_01ABC...

# Search threads
scripts/plain-api.sh thread search "billing issue"

# Get thread timeline (all messages, events, status changes)
scripts/plain-api.sh thread timeline th_01ABC... --first 50

# Paginate through timeline
scripts/plain-api.sh thread timeline th_01ABC... --first 20 --after "cursor_from_previous_page"

# Add a note to a thread (internal note, not visible to customer)
scripts/plain-api.sh thread note th_01ABC... --text "This is an internal note"

# Add a note with markdown formatting
scripts/plain-api.sh thread note th_01ABC... --text "Note text" --markdown "**Bold** and *italic*"

# Add a note from a file (for longer notes)
scripts/plain-api.sh thread note th_01ABC... --text-file /path/to/note.txt

Thread note options: | Option | Required | Description | |--------|----------|-------------| | --text | Yes* | Plain text content of the note | | --text-file | Yes* | Path to file containing note text | | --markdown | No | Markdown formatted version of the note |

*Either --text or --text-file is required.

Thread list options: | Option | Description | |--------|-------------| | --status | Filter by status: TODO, SNOOZED, DONE, or all | | --priority | Filter by priority: urgent, high, normal, low | | --customer | Filter by customer ID | | --first | Number of results (default: 10) |

Thread priorities: urgent > high > normal (default) > low

Thread Links (Read + Write)

Attach external issues (GitHub, etc.) to a thread. Plain fetches title, URL, description, and status from the integration server-side — only the ref is needed.

# Add a GitHub issue or PR — accepts URL, shorthand, or canonical sourceId
scripts/plain-api.sh thread link add th_01ABC... https://github.com/owner/repo/issues/45
scripts/plain-api.sh thread link add th_01ABC... https://github.com/owner/repo/pull/45
scripts/plain-api.sh thread link add th_01ABC... owner/repo#45
scripts/plain-api.sh thread link add th_01ABC... owner/repo/45

# List links on a thread
scripts/plain-api.sh thread link list th_01ABC...

Thread link add options: | Option | Required | Description | |--------|----------|-------------| | <thread_id> | Yes | Thread to attach the link to | | <ref> | Yes | GitHub URL, owner/repo#N, or owner/repo/N | | --source | No | Source type (default: github_issue). Other values: shortcut_issue, rootly_incident, incidentio_incident — for these, pass the integration's native sourceId as <ref> |

Notes:

• The workspace must have the relevant integration configured (e.g., GitHub) for Plain to resolve metadata. If not, the add call returns an error.
• Removing links is not supported via API key — delete from the Plain UI.
• Plain does not expose searchThreadLinkCandidates to machine users, so the agent must supply the ref directly (parse from a URL the customer pasted, etc.).

Companies (Read Only)

# List companies
scripts/plain-api.sh company list --first 10

# Get company by ID
scripts/plain-api.sh company get co_01ABC...

Tenants (Read Only)

# List tenants
scripts/plain-api.sh tenant list --first 10

# Get tenant by ID
scripts/plain-api.sh tenant get ten_01ABC...

Labels (Read Only)

# List available label types
scripts/plain-api.sh label list --first 20

Help Center (Read + Write)

# List help centers
scripts/plain-api.sh helpcenter list

# Get help center details
scripts/plain-api.sh helpcenter get hc_01ABC...

# List articles in help center
scripts/plain-api.sh helpcenter articles hc_01ABC... --first 20

# Get article by ID
scripts/plain-api.sh helpcenter article get hca_01ABC...

# Get article by slug
scripts/plain-api.sh helpcenter article get-by-slug hc_01ABC... my-article-slug

# Create new article (defaults to DRAFT status)
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "How to reset password" \
  --description "Step-by-step guide for resetting your password" \
  --content "<h1>Reset Password</h1><p>Follow these steps...</p>"

# Create and publish article directly
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "Getting Started" \
  --description "Quick start guide for new users" \
  --content "<p>Welcome!</p>" \
  --status PUBLISHED

# Update existing article
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --id hca_01ABC... \
  --title "Updated Title" \
  --description "Updated description" \
  --content "<p>New content</p>"

# Use --content-file for large HTML content (recommended)
scripts/plain-api.sh helpcenter article upsert hc_01ABC... \
  --title "Detailed Guide" \
  --description "Comprehensive documentation" \
  --content-file /path/to/article.html \
  --status PUBLISHED

# Get article group
scripts/plain-api.sh helpcenter group get hcag_01ABC...

# Create article group
scripts/plain-api.sh helpcenter group create hc_01ABC... --name "Getting Started"

# Create nested article group
scripts/plain-api.sh helpcenter group create hc_01ABC... --name "Advanced Topics" --parent hcag_01PARENT...

# Update article group
scripts/plain-api.sh helpcenter group update hcag_01ABC... --name "New Group Name"

# Delete article group
scripts/plain-api.sh helpcenter group delete hcag_01ABC...

Article upsert options: | Option | Required | Description | |--------|----------|-------------| | --title | Yes | Article title | | --description | Yes | Short description (shown in article lists) | | --content | Yes* | HTML content (inline) | | --content-file | Yes* | Path to file containing HTML content | | --id | No | Article ID (for updates) | | --group | No | Article group ID | | --status | No | DRAFT (default) or PUBLISHED |

*Either --content or --content-file is required. Use --content-file for large content.

Note: The response includes a link field with the URL to edit the article in the Plain UI:

{
  "data": { ... },
  "link": "https://app.plain.com/workspace/w_01.../help-center/hc_01.../articles/hca_01.../"
}

Tiers & SLAs (Read Only)

# List tiers with SLA configurations
scripts/plain-api.sh tier list

# Get tier details
scripts/plain-api.sh tier get tier_01ABC...

Workspace

# Get current workspace info
scripts/plain-api.sh workspace

Common Workflows

Research customer history

1. Get customer: customer get c_... or customer get-by-email [email protected]
2. List their threads: thread list --customer c_... --status all
3. Get thread details: thread get th_...
4. Read full conversation: thread timeline th_... --first 100

Read thread conversation

1. Get thread: thread get th_...
2. Fetch timeline entries: thread timeline th_... --first 50
3. Extract messages: Look for EmailEntry, ChatEntry, SlackMessageEntry, etc. in the response
4. Paginate if needed: Use --after with cursor from pageInfo.endCursor

Add internal note to thread

1. Get thread ID from URL or search: thread search "issue keyword"
2. Add note: thread note th_... --text "Investigation notes here"
3. Verify in timeline: thread timeline th_... --first 5

Create or update help article

1. List help centers: helpcenter list
2. Write HTML content to a file (for large articles): /tmp/article.html
3. Create/update article:

   helpcenter article upsert hc_... \
     --title "Article Title" \
     --description "Short description" \
     --content-file /tmp/article.html \
     --status PUBLISHED
   

4. Use the returned link to view/edit in Plain UI

Entity Reference

See references/ENTITIES.md for detailed documentation on all entities including:

• Customer fields and statuses
• Thread status, priority, and channels
• Timeline entry types (24 types: emails, chats, notes, events, status changes, etc.)
• Company and Tenant structures
• Label and LabelType definitions
• Help Center, Article, and ArticleGroup schemas
• Tier and SLA configurations

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PLAIN_API_KEY | Yes | Your Plain API key | | PLAIN_API_URL | No | API endpoint (default: https://core-api.uk.plain.com/graphql/v1) |

Output Format

All commands return JSON. Use jq for parsing:

# Get just customer name
scripts/plain-api.sh customer get c_01ABC... | jq '.data.customer.fullName'

# Get thread IDs
scripts/plain-api.sh thread list | jq '.data.threads.edges[].node.id'

# Get timeline message content
scripts/plain-api.sh thread timeline th_01ABC... | jq '.data.thread.timelineEntries.edges[].node.entry'

# Get link from article creation
scripts/plain-api.sh helpcenter article upsert hc_... --title "Test" --content "<p>Test</p>" | jq -r '.link'