> ## Documentation Index
> Fetch the complete documentation index at: https://docs.potpie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:**
1. Create integration with minimal required fields
2. Optionally add OAuth tokens via `auth_data`
3. Configure scope-specific data (org, workspace, etc.)
4. Integration is activated automatically


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

<ParamField body="name" type="string" required>
  User-friendly name for this integration (1–255 characters, e.g., "Production Sentry")
</ParamField>

<ParamField body="integration_type" type="string" required>
  Type of integration: `sentry`, `jira`, `linear`, `confluence`, `slack`, `github`
</ParamField>

<ParamField body="status" type="string" default="active">
  Integration status: `active`, `inactive`, `pending`, `error`
</ParamField>

<ParamField body="active" type="boolean" default="true">
  Whether the integration is currently active
</ParamField>

<ParamField body="unique_identifier" type="string">
  Custom unique identifier. Auto-generated as `[type]-[uuid]` if omitted.
</ParamField>

<ParamField body="auth_data" type="object">
  Authentication credentials

  <Expandable title="auth_data properties">
    <ParamField body="access_token" type="string">OAuth access token</ParamField>
    <ParamField body="refresh_token" type="string">OAuth refresh token</ParamField>
    <ParamField body="token_type" type="string" default="Bearer">Token type (e.g., `Bearer`)</ParamField>
    <ParamField body="code" type="string">OAuth authorization code</ParamField>
    <ParamField body="scope" type="string">OAuth scope string</ParamField>
    <ParamField body="expires_at" type="datetime">Token expiration timestamp (ISO 8601)</ParamField>
  </Expandable>
</ParamField>

<ParamField body="scope_data" type="object">
  Scope-specific configuration

  <Expandable title="scope_data properties">
    <ParamField body="org_slug" type="string">Organization slug</ParamField>
    <ParamField body="workspace_id" type="string">Workspace identifier</ParamField>
    <ParamField body="project_id" type="string">Project identifier</ParamField>
    <ParamField body="installation_id" type="string">Installation ID</ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional integration metadata

  <Expandable title="metadata properties">
    <ParamField body="instance_name" type="string" required>Human-readable name for this instance (required within the metadata object)</ParamField>
    <ParamField body="created_via" type="string" default="oauth_callback">How the integration was created</ParamField>
    <ParamField body="description" type="string">Description of this integration</ParamField>
    <ParamField body="tags" type="array">Tags for organization and filtering</ParamField>
    <ParamField body="version" type="string">Integration version</ParamField>
  </Expandable>
</ParamField>

#### Response

<ResponseField name="success" type="boolean">
  Whether the integration was saved successfully
</ResponseField>

<ResponseField name="data" type="object">
  Integration data if successful

  <Expandable title="data properties">
    <ResponseField name="integration_id" type="string">Unique ID generated for this integration instance</ResponseField>
    <ResponseField name="name" type="string">Name of the integration as saved</ResponseField>
    <ResponseField name="integration_type" type="string">Integration type value as saved</ResponseField>
    <ResponseField name="status" type="string">Integration status as saved</ResponseField>
    <ResponseField name="active" type="boolean">Whether the integration is currently active</ResponseField>
    <ResponseField name="unique_identifier" type="string">Unique identifier (provided or auto-generated as `[type]-[uuid]`)</ResponseField>
    <ResponseField name="created_by" type="string">User ID of the creator</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 timestamp of when the integration was created</ResponseField>
    <ResponseField name="has_auth_data" type="boolean">Whether auth data with a valid access token is present</ResponseField>
    <ResponseField name="has_scope_data" type="boolean">Whether scope data with `org_slug` or `workspace_id` is present</ResponseField>
    <ResponseField name="metadata" type="object">Full metadata object as saved</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string">
  Error message if the operation failed (null on success)
</ResponseField>

## Complete Workflow

<CodeGroup>
  ```typescript TypeScript theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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']}")
  ```

  ```bash cURL theme={null}
  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"]
      }
    }'
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "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

<CodeGroup>
  ```json Sentry theme={null}
  {
    "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"]
    }
  }
  ```

  ```json Jira theme={null}
  {
    "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"]
    }
  }
  ```

  ```json Linear theme={null}
  {
    "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"]
    }
  }
  ```

  ```json Confluence theme={null}
  {
    "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"]
    }
  }
  ```

  ```json Slack theme={null}
  {
    "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"]
    }
  }
  ```

  ```json Minimal theme={null}
  {
    "name": "My Integration",
    "integration_type": "github"
  }
  ```
</CodeGroup>

## Error Responses

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The endpoint requires a valid API key in the `x-api-key` header.

    **Missing header:**

    ```json theme={null}
    {
      "detail": "API key is required"
    }
    ```

    **Invalid key:**

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="422 Unprocessable Entity">
    Request body failed validation — a required field is missing or a field has an invalid value.

    **Missing required field:**

    ```json theme={null}
    {
      "detail": [
        {
          "loc": ["body", "name"],
          "msg": "field required",
          "type": "value_error.missing"
        }
      ]
    }
    ```

    **Invalid integration type:**

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="500 Internal Server Error">
    The endpoint catches all exceptions and returns them in a structured format.

    ```json theme={null}
    {
      "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.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml POST /api/v2/integrations/save
openapi: 3.1.0
info:
  title: Potpie API
  version: 2.0.0
  description: >-
    AI-powered codebase intelligence API. Build powerful integrations with
    Potpie's parsing, conversation, search, and agent capabilities.
  contact:
    name: Potpie Support
    email: hi@potpie.ai
    url: https://potpie.ai
  license:
    name: Proprietary
    url: https://potpie.ai/terms
servers:
  - url: http://localhost:8001
    description: Local server
security:
  - ApiKeyAuth: []
tags:
  - name: Parsing
    description: Repository parsing and status management
  - name: Projects
    description: Project management and listing
  - name: Conversations
    description: AI conversation management
  - name: Agents
    description: AI agent information and selection
  - name: Search
    description: Codebase semantic search
  - name: Integrations
    description: External service integrations
paths:
  /api/v2/integrations/save:
    post:
      tags:
        - Integrations
      summary: Save Integration
      description: >-
        Save or update an integration with external services like Sentry, Jira,
        Linear, or Confluence. Integrations enable Potpie to pull additional
        context from these platforms.
      operationId: saveIntegration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationSaveRequest'
            examples:
              sentry:
                summary: Sentry integration
                value:
                  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
              jira:
                summary: Jira integration
                value:
                  name: Main Jira Board
                  integration_type: jira
                  status: active
                  auth_data:
                    access_token: jira_token
                    refresh_token: jira_refresh
                  scope_data:
                    org_slug: mycompany
                    project_id: PROJ
      responses:
        '200':
          description: Integration saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationSaveResponse'
              examples:
                sentry:
                  summary: Sentry integration
                  value:
                    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
                jira:
                  summary: Jira integration
                  value:
                    success: true
                    data:
                      integration_id: 123e4567-e89b-12d3-a456-426614174001
                      name: Main Jira Board
                      integration_type: jira
                      status: active
                      active: true
                      unique_identifier: jira-123e4567-e89b-12d3-a456-426614174001
                      created_by: user_abc123
                      created_at: '2024-01-15T10:31:00.000000'
                      has_auth_data: true
                      has_scope_data: true
                      metadata:
                        instance_name: Main Jira Board
                        created_via: manual
                        version: null
                        description: null
                        tags: []
                    error: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    IntegrationSaveRequest:
      type: object
      required:
        - name
        - integration_type
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: User-friendly integration name
        integration_type:
          type: string
          enum:
            - sentry
            - jira
            - linear
            - confluence
            - slack
            - github
          description: Type of integration
        status:
          type: string
          enum:
            - active
            - inactive
            - pending
            - error
          default: active
          description: Integration status
        active:
          type: boolean
          default: true
          description: Whether integration is active
        auth_data:
          type: object
          properties:
            access_token:
              type: string
            refresh_token:
              type: string
            token_type:
              type: string
              default: Bearer
            expires_at:
              type: string
              format: date-time
            scope:
              type: string
            code:
              type: string
        scope_data:
          type: object
          properties:
            org_slug:
              type: string
            installation_id:
              type: string
            workspace_id:
              type: string
            project_id:
              type: string
        metadata:
          type: object
          properties:
            instance_name:
              type: string
            created_via:
              type: string
              default: manual
            description:
              type: string
            version:
              type: string
            tags:
              type: array
              items:
                type: string
        unique_identifier:
          type: string
          description: Custom identifier (auto-generated if not provided)
    IntegrationSaveResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Operation success status
        data:
          type: object
          description: Integration data if successful
        error:
          type: string
          description: Error message if failed
  responses:
    BadRequest:
      description: Bad request - Invalid parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Either repo_name or repo_path must be provided
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
          example:
            detail: Invalid API key
    ValidationError:
      description: Validation error - Invalid request body
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: array
                items:
                  type: object
                  properties:
                    loc:
                      type: array
                      items:
                        type: string
                    msg:
                      type: string
                    type:
                      type: string
          example:
            detail:
              - loc:
                  - body
                  - project_id
                msg: field required
                type: value_error.missing
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key authentication. Get your key from <a
        href="https://app.potpie.ai/settings" style="color: #60a5fa;
        font-weight: bold; text-decoration: none !important;">potpie settings
        page</a>

````