curl --request POST \
  --url http://localhost:8001/api/v2/integrations/save \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Production Sentry",
  "integration_type": "sentry",
  "status": "active",
  "auth_data": {
    "access_token": "sentry_token_here",
    "token_type": "Bearer"
  },
  "scope_data": {
    "org_slug": "my-company"
  },
  "metadata": {
    "instance_name": "Production Sentry",
    "created_via": "api",
    "tags": [
      "production",
      "monitoring"
    ]
  }
}
'

{
  "success": true,
  "data": {
    "integration_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Production Sentry",
    "integration_type": "sentry",
    "status": "active",
    "active": true,
    "unique_identifier": "sentry-123e4567-e89b-12d3-a456-426614174000",
    "created_by": "user_abc123",
    "created_at": "2024-01-15T10:30:00.000000",
    "has_auth_data": true,
    "has_scope_data": true,
    "metadata": {
      "instance_name": "Production Sentry",
      "created_via": "manual",
      "version": null,
      "description": null,
      "tags": []
    }
  },
  "error": null
}

Potpie API

Save Integration

Save a new integration configuration for third-party services like Sentry, Jira, Linear, etc.

Supported Integrations:

Sentry: Error tracking and monitoring
GitHub: Source code management
Slack: Team communication
Jira: Issue tracking
Linear: Project management
Confluence: Documentation

Integration Flow:

Create integration with minimal required fields
Optionally add OAuth tokens via auth_data
Configure scope-specific data (org, workspace, etc.)
Integration is activated automatically

POST

api

integrations

save

curl --request POST \
  --url http://localhost:8001/api/v2/integrations/save \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Production Sentry",
  "integration_type": "sentry",
  "status": "active",
  "auth_data": {
    "access_token": "sentry_token_here",
    "token_type": "Bearer"
  },
  "scope_data": {
    "org_slug": "my-company"
  },
  "metadata": {
    "instance_name": "Production Sentry",
    "created_via": "api",
    "tags": [
      "production",
      "monitoring"
    ]
  }
}
'

{
  "success": true,
  "data": {
    "integration_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Production Sentry",
    "integration_type": "sentry",
    "status": "active",
    "active": true,
    "unique_identifier": "sentry-123e4567-e89b-12d3-a456-426614174000",
    "created_by": "user_abc123",
    "created_at": "2024-01-15T10:30:00.000000",
    "has_auth_data": true,
    "has_scope_data": true,
    "metadata": {
      "instance_name": "Production Sentry",
      "created_via": "manual",
      "version": null,
      "description": null,
      "tags": []
    }
  },
  "error": null
}

Use Cases

Connect error monitoring systems for better debugging
Link issue trackers to correlate code changes
Integrate documentation platforms for reference
Set up automated workflows across tools
Enable cross-platform analysis

Request

name

string

required

User-friendly name for this integration (1–255 characters, e.g., “Production Sentry”)

integration_type

string

required

Type of integration: sentry, jira, linear, confluence, slack, github

status

string

default:"active"

Integration status: active, inactive, pending, error

active

boolean

default:"true"

Whether the integration is currently active

unique_identifier

string

Custom unique identifier. Auto-generated as [type]-[uuid] if omitted.

auth_data

object

Authentication credentials

Show auth_data properties

access_token

string

OAuth access token

refresh_token

string

OAuth refresh token

token_type

string

default:"Bearer"

Token type (e.g., Bearer)

code

string

OAuth authorization code

scope

string

OAuth scope string

expires_at

datetime

Token expiration timestamp (ISO 8601)

scope_data

object

Scope-specific configuration

Show scope_data properties

org_slug

string

Organization slug

workspace_id

string

Workspace identifier

project_id

string

Project identifier

installation_id

string

Installation ID

metadata

object

Additional integration metadata

Show metadata properties

instance_name

string

required

Human-readable name for this instance (required within the metadata object)

created_via

string

default:"oauth_callback"

How the integration was created

description

string

Description of this integration

Response

success

boolean

Whether the integration was saved successfully

data

object

Integration data if successful

Show data properties

integration_id

string

Unique ID generated for this integration instance

name

string

Name of the integration as saved

integration_type

string

Integration type value as saved

status

string

Integration status as saved

active

boolean

Whether the integration is currently active

unique_identifier

string

Unique identifier (provided or auto-generated as [type]-[uuid])

created_by

string

User ID of the creator

created_at

string

ISO 8601 timestamp of when the integration was created

has_auth_data

boolean

Whether auth data with a valid access token is present

has_scope_data

boolean

Whether scope data with org_slug or workspace_id is present

metadata

object

Full metadata object as saved

error

string

Error message if the operation failed (null on success)

Complete Workflow

const response = await fetch(
  'http://localhost:8001/api/v2/integrations/save',
  {
    method: 'POST',
    headers: {
      'x-api-key': process.env.POTPIE_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Production Sentry',
      integration_type: 'sentry',
      status: 'active',
      auth_data: {
        access_token: 'sentry_access_token_here',
        token_type: 'Bearer'
      },
      scope_data: {
        org_slug: 'my-company'
      },
      metadata: {
        instance_name: 'Production Sentry',
        created_via: 'manual',
        description: 'Error monitoring for production',
        tags: ['production', 'monitoring']
      }
    })
  }
);

const result = await response.json();
if (result.success) {
  console.log('Integration saved:', result.data);
} else {
  console.error('Failed:', result.error);
}

Success Response

{
  "success": true,
  "data": {
    "integration_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Sentry",
    "integration_type": "sentry",
    "status": "active",
    "active": true,
    "unique_identifier": "a3f1b2c4-e5d6-7890-abcd-ef1234567890",
    "created_by": "user_abc123",
    "created_at": "2025-01-15T10:30:00.000000",
    "has_auth_data": true,
    "has_scope_data": true,
    "metadata": {
      "instance_name": "Production Sentry",
      "created_via": "manual",
      "description": "Error monitoring for production",
      "tags": ["production", "monitoring"],
      "version": null
    }
  },
  "error": null
}

Integration Examples

{
  "name": "Production Sentry",
  "integration_type": "sentry",
  "status": "active",
  "auth_data": {
    "access_token": "YOUR_SENTRY_TOKEN",
    "token_type": "Bearer"
  },
  "scope_data": {
    "org_slug": "your-org"
  },
  "metadata": {
    "instance_name": "Production Sentry",
    "created_via": "manual",
    "description": "Error monitoring for production environment",
    "tags": ["production", "errors"]
  }
}

Error Responses

401 Unauthorized

The endpoint requires a valid API key in the x-api-key header.Missing header:

{
  "detail": "API key is required"
}

Invalid key:

{
  "detail": "Invalid API key"
}

Causes:

Missing x-api-key header
Invalid or expired API key

Solution: Include a valid API key in the request header.

422 Unprocessable Entity

Request body failed validation — a required field is missing or a field has an invalid value.Missing required field:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Invalid integration type:

{
  "detail": [
    {
      "loc": ["body", "integration_type"],
      "msg": "value is not a valid enumeration member",
      "type": "type_error.enum"
    }
  ]
}

Causes:

Missing required name or integration_type field
integration_type value not in: sentry, jira, linear, confluence, slack, github
Wrong data type for a field

Solution: Verify the request body matches the required field types and allowed enum values.

500 Internal Server Error

The endpoint catches all exceptions and returns them in a structured format.

{
  "success": false,
  "data": null,
  "error": "Failed to save integration: Database connection failed"
}

Causes:

Database connection failures
Invalid field values
Service unavailability

Solution: Retry the request after a brief delay. Verify all field values and contact support if the issue persists.

Troubleshooting

Integration saves but doesn't appear active

Problem: The API returns success: true but the integration seems inactive.Solution:

Check that active is set to true in the request (the default is true)
Verify status is active (the default is active)
Check the response data.active and data.has_auth_data fields
Ensure auth_data.access_token is valid and not expired

Authentication errors with valid token

Problem: Integration saves but external service authentication fails.Solution:

Verify the token has not expired — check auth_data.expires_at
Confirm the token has the required OAuth scopes for your use case
Test the token directly against the external service API
Re-authorize and save a fresh token if needed

Integration type not recognized

Problem: Request fails or the integration behaves unexpectedly for a specific type.Solution:

Use exactly one of the supported types: sentry, jira, linear, confluence, slack, github
Check for typos — the value is case-sensitive
Refer to the Integration Examples above for the correct structure per type

scope_data fields not persisted

Problem: has_scope_data returns false even after providing scope information.Solution:

The has_scope_data flag is true only when org_slug or workspace_id is present
Providing only project_id or installation_id does not set has_scope_data to true
Include org_slug (for Sentry) or workspace_id (for Jira, Confluence, Slack, Linear) in your request

Authorizations

x-api-key

string

header

required

API key authentication. Get your key from potpie settings page

Body

application/json

name

string

required

User-friendly integration name

Required string length: 1 - 255

integration_type

enum<string>

required

Type of integration

Available options:

sentry,

jira,

linear,

confluence,

slack,

github

status

enum<string>

default:active

Integration status

Available options:

active,

inactive,

pending,

error

active

boolean

default:true

Whether integration is active

auth_data

object

Show child attributes

scope_data

object

Show child attributes

metadata

object

Show child attributes

unique_identifier

string

Custom identifier (auto-generated if not provided)

Response

Integration saved successfully

success

boolean

Operation success status

data

object

Integration data if successful

error

string

Error message if failed

List Available Agents

​Use Cases

​Request

​Response

​Complete Workflow

​Success Response

​Integration Examples

​Error Responses

​Troubleshooting

Authorizations

Body

Response

Use Cases

Request

Response

Complete Workflow

Success Response

Integration Examples

Error Responses

Troubleshooting