Skip to main content
POST
/
api
/
v2
/
integrations
/
save
curl --request POST \
  --url https://production-api.potpie.ai/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
​
scope_data
object
Scope-specific configuration
​
metadata
object
Additional integration metadata

​
Response

​
success
boolean
Whether the integration was saved successfully
​
data
object
Integration data if successful
​
error
string
Error message if the operation failed (null on success)

​
Complete Workflow

const response = await fetch(
  'https://production-api.potpie.ai/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

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.
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.
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

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
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
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
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
​
scope_data
object
​
metadata
object
​
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