openapi: 3.0.3
info:
  title: Terapi API
  description: >-
    Terapi is an open-source embedded integration platform for building native
    product integrations. The REST API provides endpoints for managing
    integration connections, synchronizing data between third-party services,
    triggering actions on external APIs, and managing authentication tokens.
    Terapi enables SaaS products to offer native integrations to their customers
    without building each connector from scratch.
  version: '1.0'
  contact:
    name: Terapi Team
    url: https://terapi.dev
externalDocs:
  description: Terapi Documentation
  url: https://docs.terapi.dev
servers:
  - url: 'https://api.terapi.dev'
    description: Terapi Cloud API
  - url: 'http://localhost:3003'
    description: Terapi Self-Hosted API
tags:
  - name: Connections
    description: Manage end-user connections to third-party integrations
  - name: Integrations
    description: Manage available integration configurations
  - name: Sync
    description: Trigger and manage data synchronization between services
  - name: Actions
    description: Trigger actions on connected third-party services
  - name: Authentication
    description: Manage authentication and token refresh for integrations
security:
  - SecretKeyAuth: []
paths:
  /connection:
    get:
      operationId: listConnections
      summary: List Connections
      description: >-
        Returns a list of all active connections for a given integration or
        provider. Connections represent authenticated links between end-user
        accounts and third-party services.
      tags:
        - Connections
      parameters:
        - name: provider_config_key
          in: query
          description: Filter connections by integration provider config key
          schema:
            type: string
        - name: connection_id
          in: query
          description: Filter by a specific connection ID
          schema:
            type: string
      responses:
        '200':
          description: Connections retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createConnection
      summary: Create Connection
      description: >-
        Creates a new integration connection for an end-user with the specified
        provider. Used to programmatically create connections when auth tokens
        are already available.
      tags:
        - Connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionRequest'
      responses:
        '200':
          description: Connection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /connection/{connection_id}:
    get:
      operationId: getConnection
      summary: Get Connection
      description: >-
        Returns details of a specific connection including its authentication
        status and metadata.
      tags:
        - Connections
      parameters:
        - name: connection_id
          in: path
          required: true
          description: The unique identifier of the connection
          schema:
            type: string
        - name: provider_config_key
          in: query
          required: true
          description: The provider config key for this connection
          schema:
            type: string
      responses:
        '200':
          description: Connection retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteConnection
      summary: Delete Connection
      description: >-
        Deletes a connection and revokes associated credentials. The end-user
        will need to re-authenticate to restore the connection.
      tags:
        - Connections
      parameters:
        - name: connection_id
          in: path
          required: true
          description: The unique identifier of the connection
          schema:
            type: string
        - name: provider_config_key
          in: query
          required: true
          description: The provider config key for this connection
          schema:
            type: string
      responses:
        '204':
          description: Connection deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /integration:
    get:
      operationId: listIntegrations
      summary: List Integrations
      description: >-
        Returns a list of all configured integrations (provider configurations)
        in your Terapi environment.
      tags:
        - Integrations
      responses:
        '200':
          description: Integrations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createIntegration
      summary: Create Integration
      description: >-
        Creates a new integration configuration with credentials for a
        third-party provider. This enables end-users to connect to this
        provider.
      tags:
        - Integrations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationRequest'
      responses:
        '200':
          description: Integration created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /integration/{provider_config_key}:
    get:
      operationId: getIntegration
      summary: Get Integration
      description: Returns details of a specific integration configuration.
      tags:
        - Integrations
      parameters:
        - name: provider_config_key
          in: path
          required: true
          description: The unique key for this integration configuration
          schema:
            type: string
      responses:
        '200':
          description: Integration retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteIntegration
      summary: Delete Integration
      description: >-
        Deletes an integration configuration. All associated connections will
        also be deleted.
      tags:
        - Integrations
      parameters:
        - name: provider_config_key
          in: path
          required: true
          description: The unique key for this integration configuration
          schema:
            type: string
      responses:
        '204':
          description: Integration deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /sync/trigger:
    post:
      operationId: triggerSync
      summary: Trigger Sync
      description: >-
        Triggers a data synchronization run for a specific connection and sync
        configuration. The sync fetches updated data from the third-party
        provider.
      tags:
        - Sync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerSyncRequest'
      responses:
        '200':
          description: Sync triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncTriggerResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sync/{connection_id}/{sync_name}:
    get:
      operationId: getSyncStatus
      summary: Get Sync Status
      description: Returns the current status and history of a specific sync.
      tags:
        - Sync
      parameters:
        - name: connection_id
          in: path
          required: true
          description: The connection identifier
          schema:
            type: string
        - name: sync_name
          in: path
          required: true
          description: The name of the sync
          schema:
            type: string
        - name: provider_config_key
          in: query
          required: true
          description: The provider config key
          schema:
            type: string
      responses:
        '200':
          description: Sync status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /action/trigger:
    post:
      operationId: triggerAction
      summary: Trigger Action
      description: >-
        Triggers an action on a connected third-party service via the specified
        connection. Actions are write operations like creating a record,
        sending a message, or updating a resource.
      tags:
        - Actions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerActionRequest'
      responses:
        '200':
          description: Action triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /auth/token/{provider_config_key}/{connection_id}:
    get:
      operationId: getAuthToken
      summary: Get Authentication Token
      description: >-
        Returns the current authentication token for a connection. Terapi
        automatically refreshes OAuth tokens as needed before returning.
      tags:
        - Authentication
      parameters:
        - name: provider_config_key
          in: path
          required: true
          description: The provider config key
          schema:
            type: string
        - name: connection_id
          in: path
          required: true
          description: The connection identifier
          schema:
            type: string
        - name: force_refresh
          in: query
          description: Force a token refresh even if the current token is still valid
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Token retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    SecretKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Secret key from Terapi environment settings. Passed as
        'Bearer {secret_key}'
  responses:
    Unauthorized:
      description: Authentication failed - invalid or missing secret key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters or body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Connection:
      type: object
      description: An authenticated connection between an end-user and a third-party service
      properties:
        id:
          type: string
          description: Unique connection identifier (set by your application)
        provider_config_key:
          type: string
          description: The integration provider config key
        provider:
          type: string
          description: The third-party provider name (e.g., github, salesforce)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        metadata:
          type: object
          description: Custom metadata stored with this connection
          additionalProperties: true
        credentials:
          type: object
          description: Current credential state (no raw secrets returned)
          properties:
            type:
              type: string
              description: Credential type (oauth2, api_key, basic)
            expires_at:
              type: string
              format: date-time
    ConnectionListResponse:
      type: object
      properties:
        connections:
          type: array
          items:
            $ref: '#/components/schemas/Connection'
    CreateConnectionRequest:
      type: object
      required:
        - connection_id
        - provider_config_key
      properties:
        connection_id:
          type: string
          description: Your application's unique identifier for this connection
        provider_config_key:
          type: string
          description: The integration provider config key
        credentials:
          type: object
          description: Authentication credentials to store for this connection
          additionalProperties: true
        metadata:
          type: object
          description: Custom metadata to store with this connection
          additionalProperties: true
    Integration:
      type: object
      description: An integration configuration for a third-party provider
      properties:
        unique_key:
          type: string
          description: Your unique key for this integration configuration
        provider:
          type: string
          description: The provider name (e.g., github, salesforce, slack)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        connection_count:
          type: integer
          description: Number of active connections using this integration
    IntegrationListResponse:
      type: object
      properties:
        integrations:
          type: array
          items:
            $ref: '#/components/schemas/Integration'
    CreateIntegrationRequest:
      type: object
      required:
        - provider_config_key
        - provider
      properties:
        provider_config_key:
          type: string
          description: Your unique key for this integration configuration
        provider:
          type: string
          description: The provider name from Terapi's supported providers list
        oauth_client_id:
          type: string
          description: OAuth client ID for OAuth2 providers
        oauth_client_secret:
          type: string
          description: OAuth client secret for OAuth2 providers
        oauth_scopes:
          type: string
          description: Comma-separated list of OAuth scopes to request
    TriggerSyncRequest:
      type: object
      required:
        - connection_id
        - provider_config_key
        - syncs
      properties:
        connection_id:
          type: string
          description: The connection to sync for
        provider_config_key:
          type: string
          description: The provider config key
        syncs:
          type: array
          description: Names of syncs to trigger
          items:
            type: string
    SyncTriggerResponse:
      type: object
      properties:
        success:
          type: boolean
        syncs:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              status:
                type: string
    SyncStatus:
      type: object
      description: Status and history of a data synchronization
      properties:
        sync_name:
          type: string
        connection_id:
          type: string
        status:
          type: string
          enum:
            - running
            - success
            - error
            - paused
        last_sync_date:
          type: string
          format: date-time
        next_sync_date:
          type: string
          format: date-time
        records_count:
          type: integer
          description: Total number of records synced
        error:
          type: string
          description: Error message if sync failed
    TriggerActionRequest:
      type: object
      required:
        - connection_id
        - provider_config_key
        - action_name
      properties:
        connection_id:
          type: string
          description: The connection to perform the action on
        provider_config_key:
          type: string
          description: The provider config key
        action_name:
          type: string
          description: The name of the action to trigger
        input:
          type: object
          description: Input parameters for the action
          additionalProperties: true
    ActionResponse:
      type: object
      description: Result of a triggered action
      properties:
        success:
          type: boolean
        action_name:
          type: string
        output:
          type: object
          description: Output data returned by the action
          additionalProperties: true
        error:
          type: string
          description: Error message if action failed
    AuthToken:
      type: object
      description: Authentication token for a connection
      properties:
        type:
          type: string
          description: Token type (Bearer, ApiKey, etc.)
        access_token:
          type: string
          description: The access token value
        expires_at:
          type: string
          format: date-time
          description: Token expiration time
        raw:
          type: object
          description: Full raw token response from the provider
          additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Human-readable error message