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
/
v2
/
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
string
required
User-friendly name for this integration (1–255 characters, e.g., “Production Sentry”)
string
required
Type of integration:
sentry, jira, linear, confluence, slack, githubstring
default:"active"
Integration status:
active, inactive, pending, errorboolean
default:"true"
Whether the integration is currently active
string
Custom unique identifier. Auto-generated as
[type]-[uuid] if omitted.object
object
object
Additional integration metadata
Response
boolean
Whether the integration was saved successfully
object
Integration data if successful
Show data properties
Show data properties
string
Unique ID generated for this integration instance
string
Name of the integration as saved
string
Integration type value as saved
string
Integration status as saved
boolean
Whether the integration is currently active
string
Unique identifier (provided or auto-generated as
[type]-[uuid])string
User ID of the creator
string
ISO 8601 timestamp of when the integration was created
boolean
Whether auth data with a valid access token is present
boolean
Whether scope data with
org_slug or workspace_id is presentobject
Full metadata object as saved
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);
}
import requests
response = requests.post(
'http://localhost:8001/api/v2/integrations/save',
headers={
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'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']
}
}
)
result = response.json()
if result['success']:
print(f"Integration saved: {result['data']}")
else:
print(f"Failed: {result['error']}")
curl -X POST \
'http://localhost:8001/api/v2/integrations/save' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"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"]
}
}'
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"]
}
}
{
"name": "Engineering Jira",
"integration_type": "jira",
"status": "active",
"auth_data": {
"access_token": "YOUR_JIRA_TOKEN",
"token_type": "Bearer"
},
"scope_data": {
"workspace_id": "your-jira-domain.atlassian.net"
},
"metadata": {
"instance_name": "Engineering Jira",
"created_via": "manual",
"description": "Issue tracking for engineering team",
"tags": ["jira", "issues"]
}
}
{
"name": "Product Linear",
"integration_type": "linear",
"status": "active",
"auth_data": {
"access_token": "YOUR_LINEAR_TOKEN",
"token_type": "Bearer"
},
"scope_data": {
"workspace_id": "your-workspace-id"
},
"metadata": {
"instance_name": "Product Linear",
"created_via": "manual",
"description": "Issue tracking via Linear",
"tags": ["linear", "issues"]
}
}
{
"name": "Team Confluence",
"integration_type": "confluence",
"status": "active",
"auth_data": {
"access_token": "YOUR_CONFLUENCE_TOKEN",
"token_type": "Bearer"
},
"scope_data": {
"workspace_id": "your-confluence-domain.atlassian.net"
},
"metadata": {
"instance_name": "Team Confluence",
"created_via": "manual",
"description": "Documentation platform integration",
"tags": ["confluence", "docs"]
}
}
{
"name": "Engineering Slack",
"integration_type": "slack",
"status": "active",
"auth_data": {
"access_token": "YOUR_SLACK_BOT_TOKEN",
"token_type": "Bearer"
},
"scope_data": {
"workspace_id": "T0123456789"
},
"metadata": {
"instance_name": "Engineering Slack",
"created_via": "manual",
"description": "Slack notifications for engineering",
"tags": ["slack", "notifications"]
}
}
{
"name": "My Integration",
"integration_type": "github"
}
Error Responses
401 Unauthorized
401 Unauthorized
The endpoint requires a valid API key in the Invalid key:Causes:
x-api-key header.Missing header:{
"detail": "API key is required"
}
{
"detail": "Invalid API key"
}
- Missing
x-api-keyheader - Invalid or expired API key
422 Unprocessable Entity
422 Unprocessable Entity
Request body failed validation — a required field is missing or a field has an invalid value.Missing required field:Invalid integration type:Causes:
{
"detail": [
{
"loc": ["body", "name"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
{
"detail": [
{
"loc": ["body", "integration_type"],
"msg": "value is not a valid enumeration member",
"type": "type_error.enum"
}
]
}
- Missing required
nameorintegration_typefield integration_typevalue not in:sentry,jira,linear,confluence,slack,github- Wrong data type for a field
500 Internal Server Error
500 Internal Server Error
The endpoint catches all exceptions and returns them in a structured format.Causes:
{
"success": false,
"data": null,
"error": "Failed to save integration: Database connection failed"
}
- Database connection failures
- Invalid field values
- Service unavailability
Troubleshooting
Integration saves but doesn't appear active
Integration saves but doesn't appear active
Problem: The API returns
success: true but the integration seems inactive.Solution:- Check that
activeis set totruein the request (the default istrue) - Verify
statusisactive(the default isactive) - Check the response
data.activeanddata.has_auth_datafields - Ensure
auth_data.access_tokenis valid and not expired
Authentication errors with valid token
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
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
scope_data fields not persisted
Problem:
has_scope_data returns false even after providing scope information.Solution:- The
has_scope_dataflag istrueonly whenorg_slugorworkspace_idis present - Providing only
project_idorinstallation_iddoes not sethas_scope_datatotrue - Include
org_slug(for Sentry) orworkspace_id(for Jira, Confluence, Slack, Linear) in your request
Authorizations
API key authentication. Get your key from potpie settings page
Body
application/json
User-friendly integration name
Required string length:
1 - 255Type of integration
Available options:
sentry, jira, linear, confluence, slack, github Integration status
Available options:
active, inactive, pending, error Whether integration is active
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Custom identifier (auto-generated if not provided)
Was this page helpful?

