Prismatic API

Reference documentation for Prismatic platform operations and the standardized API access hierarchy.

API Access Method Hierarchy

Prismatic API access follows a two-tier priority system for interactive agents (e.g., Orby). Builder agents (cni-builder, component-builder) use their own script-based pipelines and should not use MCP tools directly — see their agent docs for details.

Priority 1: MCP Tools (Interactive Agents Only)

Use MCP tools when operating within an interactive agent conversation (e.g., Orby). These handle auth, retries, and output formatting automatically.

mcp__plugin_prismatic-skills_prism__prism_me

mcp__plugin_prismatic-skills_prism__prism_components_list

mcp__plugin_prismatic-skills_prism__prism_components_init

mcp__plugin_prismatic-skills_prism__prism_components_publish

mcp__plugin_prismatic-skills_prism__prism_components_generate_manifest

mcp__plugin_prismatic-skills_prism__prism_integrations_list

mcp__plugin_prismatic-skills_prism__prism_integrations_init

mcp__plugin_prismatic-skills_prism__prism_integrations_import

mcp__plugin_prismatic-skills_prism__prism_integrations_convert

mcp__plugin_prismatic-skills_prism__prism_integrations_flows_list

mcp__plugin_prismatic-skills_prism__prism_integrations_flows_test

mcp__plugin_prismatic-skills_prism__prism_integrations_flows_listen

mcp__plugin_prismatic-skills_prism__prism_integrations_generate_flow

mcp__plugin_prismatic-skills_prism__prism_integrations_generate_config_page

mcp__plugin_prismatic-skills_prism__prism_integrations_generate_config_var

mcp__plugin_prismatic-skills_prism__prism_integrations_add_connection_config_var

mcp__plugin_prismatic-skills_prism__prism_integrations_add_datasource_config_var

mcp__plugin_prismatic-skills_prism__prism_install_component_manifest

mcp__plugin_prismatic-skills_prism__prism_install_legacy_component_manifest

Priority 2: Prism CLI (Scripts + Agents)

For scripts and operations not covered by MCP tools:

Built-in commands (via

prism-retry.ts

prism integrations:list --extended --output json
prism components:publish --directory ./my-component
prism integrations:import --directory ./my-integration

Custom GraphQL queries (via

shared/graphql.ts

import { graphql, GraphQLError } from "./shared/graphql.js";

const data = graphql('query { customers { nodes { id name } } }');

Or directly via CLI:

prism graphql:query 'query { customers { nodes { id name } } }'
prism graphql:query 'query($id: ID!) { customer(id: $id) { name } }' \
  --variables '{"id": "Q3VzdG9tZXI6..."}'

Decision Tree

Agent calling directly?  → Use MCP tool if available, else `prism` via Bash
Script?                  → Use shared/graphql.ts for custom queries,
                           prism-retry.ts for built-in CLI commands

Rule: NEVER create inline GraphQL clients — always use

shared/graphql.ts

Common Operations Cheat Sheet

These are the most frequently needed GraphQL operations. Use these exact queries — don't guess the field names.

references/instances.md

instances(integration: $id, isSystem: true)

references/execution-and-logs.md

executionResult(id: $id)

references/integrations.md

publishIntegration(input: { id: $id })

references/integrations.md

updateIntegrationMarketplaceConfiguration

references/instances.md

updateInstance(input: { id: $id, persistedData: "{}" })

references/instances.md

updateInstanceConfigVariables

updateInstance

Read the referenced file section for the full query with all fields. Do not reconstruct queries from memory.

CLI Usage Rules

1. prism

   must be installed globally (

   npm install -g @prismatic-io/prism

   ) — never use

   npx prism

2. All list commands: always use

   --extended --output json

3. --extended

   and

   --columns

   are mutually exclusive — always prefer

   --extended

4. For

   graphql:query

   : always use

   --variables

   flag, never string interpolation
5. Auth is handled by the CLI — no custom token exchange needed

API Endpoint

• URL:

  {PRISMATIC_URL}/api

  (default:

  https://app.prismatic.io/api

  )
• Method: HTTP POST with JSON body

  {"query": "...", "variables": {}}

• Auth: Bearer token in

  Authorization

  header
• Content-Type:

  application/json

Authentication

Obtain tokens via Prism CLI. See

references/authentication.md

Quick reference:

• prism me:token

  - Short-lived access token

• prism me:token --type refresh

  - Long-lived refresh token
• Access tokens valid for 7 days, auto-refreshed 5 minutes before expiry
• All authenticated requests return HTTP 200, even on errors - always check

  errors

  array

Pagination

All collection queries use Relay cursor-based pagination. See

references/pagination-and-filtering.md

query($after: String) {
  resources(after: $after, first: 100) {
    nodes { id name }
    pageInfo { hasNextPage endCursor }
  }
}

Critical Patterns

1. Enum values are lowercase strings:

   variableScope: "customer"

   not

   "CUSTOMER"

   ,

   managedBy: "org"

   not

   "ORG"

2. Use

   updateInstanceConfigVariables

   (partial, safe) not

   updateInstance

   (replaces ALL config vars)
3. Always deploy after config changes: Call

   deployInstance

   to activate
4. Use parameterized variables: Never string-concatenate into queries
5. Check mutation errors: Mutations return

   errors { field messages }

   alongside results

Key References by Resource Type

Core Resources

• references/customers.md

  - Customer CRUD, external IDs, labels

• references/integrations.md

  - Integration management, publishing, testing

• references/instances.md

  - Instance deployment, config variables, lifecycle

• references/components.md

  - Component queries, action introspection, search

Connections & Config

• references/connections.md

  - Scoped config vars, customer config vars, connection management

• references/config-variables.md

  - Instance config updates, deployment patterns

Operational

• references/execution-and-logs.md

  - Execution results, step results, log queries, replay

• references/common-patterns.md

  - Batch operations, nested queries, aliased mutations, error handling

• references/api-access-methods.md

  - Detailed MCP tool reference, CLI patterns, migration notes