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 user@example.com

# 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

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

Get customer: customer get c_... or customer get-by-email user@example.com
List their threads: thread list --customer c_... --status all
Get thread details: thread get th_...
Read full conversation: thread timeline th_... --first 100

Read thread conversation

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

Add internal note to thread

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

Create or update help article

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

Create/update article:

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

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'

plain-support

Safety Notice

Copy this and send it to your AI assistant to learn