Integration API Reference

This document provides a detailed reference for the data structures you’ll use when building an integration for Pixelstack. For a step-by-step guide on how to build an integration, see the Build an Integration page.

IntegrationManifest

The IntegrationManifest is a JSON object that defines the core configuration and capabilities of your integration.

{
  "name": "My Awesome Integration",
  "description": "A brief description of what this integration does.",
  "iconUrl": "https://example.com/icon.png",
  "handlerUrl": "https://api.example.com/pixelstack-handler",
  "supportedEvents": ["loadImages", "nodeCalled"],
  "settings": [
    {
      "id": "apiKey",
      "name": "API Key",
      "description": "Your API Key for My Awesome Service.",
      "type": "string",
      "isSecret": true
    }
  ],
  "imageLoader": {
    "formInputs": [
      {
        "id": "query",
        "name": "Search term",
        "type": "string",
        "required": true
      }
    ],
    "formSubmitLabel": "Search"
  },
  "nodeTypes": [
    {
      "id": "my-node",
      "name": "My Custom Node",
      "description": "This node does something awesome.",
      "inputs": [{ "id": "input-data", "name": "Input Data", "type": "string" }],
      "outputs": [{ "id": "output-data", "name": "Output Data", "type": "string" }]
    }
  ]
}

Manifest Properties

• name (string): The display name of your integration.
• description (string): A brief summary of what your integration does.
• iconUrl (string): A URL to an icon for your integration.
• handlerUrl (string): The public URL where Pixelstack will send event payloads.
• supportedEvents (IntegrationEvent[]): An array of event types your integration will listen to.
• settings (IntegrationSetting[]): An array of configuration settings the user needs to provide.
• imageLoader (IntegrationImageLoader): The configuration for the image loader UI, if your integration provides one.
• nodeTypes (IntegrationNodeType[]): An array of custom workflow nodes provided by your integration.

---

Shared Data Structures

IntegrationSetting

Defines a configuration field that users will fill out in Pixelstack to set up your integration.

• id (string): A unique identifier for the setting.
• name (string): The display name for the setting field.
• description (string): A description of what the setting is for.
• type (IntegrationFieldType): The data type for the setting’s value.
• editor (IntegrationFieldEditor): An optional UI control for editing the field.
• isSecret (boolean): If true, the value will be encrypted and hidden in the UI.

IntegrationNodeType

Defines a custom node that can be used in Pixelstack workflows.

• id (string): A unique identifier for this node type.
• name (string): The display name of the node.
• description (string): A description of what the node does.
• inputs (IntegrationNodeTypeInput[]): An array of input sockets for the node.
• outputs (IntegrationNodeTypeOutput[]): An array of output sockets for the node.
• controls (IntegrationNodeTypeControl[]): An array of UI controls to display on the node itself.

IntegrationImageLoader

Defines the UI for an image loader that appears in the Pixelstack editor.

• formInputs (IntegrationNodeTypeInput[]): An array of input fields for the image search/load form.
• formSubmitLabel (string): The label for the form’s submit button.

IntegrationNodeTypeInput

Defines an input socket for a custom node. Also used for form inputs in an IntegrationImageLoader.

• id (string): A unique identifier for the input.
• name (string): The display name for the input field.
• type (IntegrationFieldType): The data type for the input’s value.
• editor (IntegrationFieldEditor): An optional UI control for editing the field.
• required (boolean): If true, a value must be provided for this input.

IntegrationNodeTypeOutput

Defines an output socket for a custom node.

• id (string): A unique identifier for the output.
• name (string): The display name for the output socket.
• type (IntegrationFieldType): The data type for the output’s value.

IntegrationNodeTypeControl

Defines a UI control shown directly on the node in the workflow editor. It has the same properties as IntegrationNodeTypeInput, with the addition of an optional value property to set a default.

IntegrationValue

Represents a value provided to or returned from a node during a workflow run. It’s used for inputValues, outputValues, and controlValues.

• id (string): The id of the corresponding input, output, or control.
• value (any): The actual value.

---

Field & Event Types

IntegrationFieldType

The possible data types for input, output, setting, and control fields.

Value	Description
'string'	A string of text.
'number'	A numeric value.
'json'	A JSON object, represented as a string.
'boolean'	A true or false value.

IntegrationFieldEditor

Optional UI hints to display a special editor for a field.

Value	Description
'colorPicker'	A visual color selector.
'timePicker'	A control for selecting a time.
'datePicker'	A control for selecting a date.

IntegrationEvent

The types of events your handler can subscribe to.

Value	Description
'loadImages'	Fired when a user uses your image loader.
'nodeCalled'	Fired when a workflow executes one of your nodes.
'installed'	Fired when a user installs your integration.
'settingsUpdated'	Fired when a user updates your integration’s settings.
'deleted'	Fired when a user uninstalls your integration.

---

Event Payloads & Responses

When an event your integration is subscribed to occurs, Pixelstack sends a POST request to your handlerUrl. The body of this request is a JSON object with a common structure:

• teamId (string): The ID of the team that triggered the event.
• eventType (IntegrationEvent): The type of event that occurred.
• settingValues (IntegrationSettingValue[]): The current values for the settings defined in your manifest.
• eventData (object): An object containing data specific to the event.

For full request and response examples, see the Build an Integration guide.

IntegrationSettingValue

Represents the configured value for one of your integration’s settings.

• id (string): The id of the IntegrationSetting.
• value (any): The value provided by the user.

---

loadImages

Fired when a user interacts with your image loader.

The eventData object will contain the values from the formInputs you defined in your manifest’s imageLoader object.

Your handler must return an IntegrationImageLoaderResponse object.

IntegrationImageLoaderResponse

The response should be a JSON object with a single images property.

• images (IntegrationImageLoaderItem[]): An array of images to display.

IntegrationImageLoaderItem

Describes a single image to be displayed in the loader.

• imageUrl (string): The URL for the full-resolution image.
• thumbnailUrl (string): The URL for a smaller thumbnail version of the image.
• title (string, optional): An optional title to display for the image.
• subtitle (string, optional): An optional subtitle or credit to display for the image.

---

nodeCalled

Fired when a workflow executes one of your custom nodes.

The eventData object contains:

• nodeTypeId (string): The ID of the node being called.
• inputValues (IntegrationValue[]): The values from the node’s inputs.
• controlValues (IntegrationValue[]): The values from the node’s on-screen controls.

Your handler should return a JSON object containing an outputs array. Each item in the array is an IntegrationValue object, representing an output from your node.